Merge branch 'main' into fix/use-native-modal-dialog

.cspell.json

@@ -21,11 +21,13 @@
   ],
   "ignorePaths": [
     "CHANGELOG.md",
+    "patches",
     "packages/docusaurus-theme-translations/locales",
     "package.json",
     "yarn.lock",
     "project-words.txt",
     "__snapshots__",
+    "admin/scripts",
     "website/src/data/users.tsx",
     "website/src/data/tweets.tsx",
     "website/docusaurus.config.localized.json",

.devcontainer/devcontainer.json

@@ -1,32 +1,36 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
-  "settings": {
+  "customizations": {
-    "[typescript]": {
+    "vscode": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
+      "settings": {
-      "editor.formatOnSave": true
+        "[typescript]": {
-    },
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "[json]": {
+          "editor.formatOnSave": true
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
+        },
-      "editor.formatOnSave": true
+        "[json]": {
-    },
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "[jsonc]": {
+          "editor.formatOnSave": true
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
+        },
-      "editor.formatOnSave": true
+        "[jsonc]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        }
+      },
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "orta.vscode-jest",
+        "esbenp.prettier-vscode",
+        "streetsidesoftware.code-spell-checker"
+      ]
     }
   },
-  "extensions": [
-    "dbaeumer.vscode-eslint",
-    "orta.vscode-jest",
-    "esbenp.prettier-vscode",
-    "streetsidesoftware.code-spell-checker"
-  ],
   "forwardPorts": [3000],
   "containerUser": "vscode",
   "postCreateCommand": "yarn install",
   "waitFor": "postCreateCommand", // otherwise automated jest tests fail
   "features": {
     "node": {
-      "version": "18"
+      "version": "22"
     },
     "github-cli": "latest"
   }

.eslintrc.js

@@ -380,7 +380,14 @@ module.exports = {
     // We don't provide any escape hatches for this rule. Rest siblings and
     // function placeholder params are always ignored, and any other unused
     // locals must be justified with a disable comment.
-    '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
+    '@typescript-eslint/no-unused-vars': [
+      ERROR,
+      {
+        ignoreRestSiblings: true,
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
     '@typescript-eslint/prefer-optional-chain': ERROR,
     '@docusaurus/no-html-links': ERROR,
     '@docusaurus/prefer-docusaurus-heading': ERROR,

.github/workflows/argos.yml

@@ -30,7 +30,7 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
 

.github/workflows/build-blog-only.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/build-hash-router.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/build-perf.yml

@@ -43,12 +43,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Track build size changes
-        uses: preactjs/compressed-size-action@6fa0e7ca017120c754863b31123c5ee2860fd434 # v2
+        uses: preactjs/compressed-size-action@946a292cd35bd1088e0d7eb92b69d1a8d5b5d76a # v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           build-script: build:website:fast
@@ -75,7 +75,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/canary-release.yml

@@ -24,7 +24,7 @@ jobs:
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/continuous-releases.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/dependency-review.yml

@@ -15,4 +15,4 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Dependency Review
-        uses: actions/dependency-review-action@4081bf99e2866ebe428fc0477b69eb4fcda7220a # 4.4.0
+        uses: actions/dependency-review-action@3b139cfc5fae8b618d3eae3675e383bb1769c019 # 4.5.0

.github/workflows/lighthouse-report.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
 
@@ -64,7 +64,7 @@ jobs:
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # 2.9.0
+        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # 2.9.1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lint.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn
@@ -33,7 +33,7 @@ jobs:
 
       - name: Check for suspicious yarn.lock
         # for allowed aliases, see https://github.com/yargs/cliui/pull/139/files#r1670711112
-        run: yarn lockfile-lint --path yarn.lock --type yarn --allowed-hosts yarn --validate-https --validate-package-names --validate-integrity --empty-hostname=false --allowed-package-name-aliases react-loadable string-width-cjs strip-ansi-cjs wrap-ansi-cjs
+        run: yarn lockfile-lint --path yarn.lock --type yarn --allowed-hosts yarn --validate-https --validate-package-names --validate-integrity --empty-hostname=false --allowed-package-name-aliases react-loadable react-helmet-async string-width-cjs strip-ansi-cjs wrap-ansi-cjs
 
       - name: Lint
         run: |

.github/workflows/showcase-test.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-e2e.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -68,7 +68,7 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
@@ -84,7 +84,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn
@@ -153,7 +153,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn
@@ -181,7 +181,7 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
@@ -193,7 +193,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn
@@ -223,6 +223,6 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website

.github/workflows/tests-swizzle.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-windows.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: ${{ matrix.node }}
       - name: Installation

.github/workflows/tests.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -49,7 +49,7 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=400'
+          NODE_OPTIONS: '--max-old-space-size=450'
           DOCUSAURUS_PERF_LOGGER: 'true'
       - name: Docusaurus site CSS order
         run: yarn workspace website test:css-order

.prettierignore

@@ -4,6 +4,7 @@ node_modules
 build
 coverage
 .docusaurus
+.idea
 
 .svg
 *.svg

CHANGELOG.md

@@ -1,5 +1,92 @@
 # Docusaurus Changelog
 
+## 3.7.0 (2025-01-03)
+
+#### :rocket: New Feature
+
+- `docusaurus-faster`, `docusaurus`
+  - [#10800](https://github.com/facebook/docusaurus/pull/10800) feat(core): Turn Rspack incremental on by default (again) ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
+  - [#10768](https://github.com/facebook/docusaurus/pull/10768) feat(blog): Add author social icons for bluesky, mastodon, threads, twitch, youtube, instagram ([@GingerGeek](https://github.com/GingerGeek))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-module-type-aliases`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-google-tag-manager`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-rsdoctor`, `docusaurus-plugin-sitemap`, `docusaurus-plugin-svgr`, `docusaurus-plugin-vercel-analytics`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-mermaid`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus`
+  - [#10763](https://github.com/facebook/docusaurus/pull/10763) feat: Add React 19 support to Docusaurus v3 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`
+  - [#10729](https://github.com/facebook/docusaurus/pull/10729) feat(blog): Add `frontMatter.sidebar_label` ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`, `docusaurus-plugin-svgr`, `docusaurus-preset-classic`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#10677](https://github.com/facebook/docusaurus/pull/10677) feat(svgr): create new Docusaurus SVGR plugin ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#10803](https://github.com/facebook/docusaurus/pull/10803) fix(npm-to-yarn): add missing npm-to-yarn converter for Bun ([@Lehoczky](https://github.com/Lehoczky))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#10796](https://github.com/facebook/docusaurus/pull/10796) fix(theme): Footer Column/Link should merge provided className ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-theme-common`
+  - [#10786](https://github.com/facebook/docusaurus/pull/10786) fix(core): fix React hydration errors, change html minifier settings ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#10782](https://github.com/facebook/docusaurus/pull/10782) fix(theme-common): code block magic comments should support SQL block comments ([@WillBlack403](https://github.com/WillBlack403))
+- `docusaurus-theme-translations`
+  - [#10783](https://github.com/facebook/docusaurus/pull/10783) fix(theme-translations): Add missing Dutch (nl) theme translations ([@janaukema](https://github.com/janaukema))
+  - [#10760](https://github.com/facebook/docusaurus/pull/10760) fix(theme-translation): add missing Korean (ko) theme translations ([@effozen](https://github.com/effozen))
+- `docusaurus-plugin-content-docs`
+  - [#10754](https://github.com/facebook/docusaurus/pull/10754) fix(docs): fix sidebar item visibility bug for category index ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10727](https://github.com/facebook/docusaurus/pull/10727) fix(core): fix codegen routesChunkName possible hash collision ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`
+  - [#10723](https://github.com/facebook/docusaurus/pull/10723) fix(mdx-loader): fix md image paths with spaces bug related to transformImage encoding problem ([@slorber](https://github.com/slorber))
+
+#### :memo: Documentation
+
+- [#10740](https://github.com/facebook/docusaurus/pull/10740) docs: Link initialization docs together ([@waldyrious](https://github.com/waldyrious))
+
+#### :robot: Dependencies
+
+- [#10771](https://github.com/facebook/docusaurus/pull/10771) chore(deps): bump nanoid from 3.3.7 to 3.3.8 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10721](https://github.com/facebook/docusaurus/pull/10721) chore(deps): bump actions/dependency-review-action from 4.4.0 to 4.5.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :wrench: Maintenance
+
+- Other
+  - [#10770](https://github.com/facebook/docusaurus/pull/10770) chore: Devcontainer upgrade to Ubuntu Noble & Node 22 ([@GingerGeek](https://github.com/GingerGeek))
+- `docusaurus-theme-search-algolia`
+  - [#10801](https://github.com/facebook/docusaurus/pull/10801) refactor(algolia): simplify SearchBar component ([@slorber](https://github.com/slorber))
+  - [#10672](https://github.com/facebook/docusaurus/pull/10672) chore(algolia): upgrade algoliasearch to v5 ([@millotp](https://github.com/millotp))
+- `docusaurus`
+  - [#10798](https://github.com/facebook/docusaurus/pull/10798) refactor(core): Use Intl native API to get locale direction, remove rtl-detect depend… ([@slorber](https://github.com/slorber))
+  - [#10747](https://github.com/facebook/docusaurus/pull/10747) refactor(core): swizzle wrap should use ReactNode instead of JSX.Element ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-module-type-aliases`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-mermaid`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus`
+  - [#10746](https://github.com/facebook/docusaurus/pull/10746) refactor: prepare types for React 19 ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#10728](https://github.com/facebook/docusaurus/pull/10728) refactor(theme-common): change storageUtils useSyncExternalCode getSnapshot workaround ([@slorber](https://github.com/slorber))
+
+#### Committers: 14
+
+- Alvin Bryan ([@alvinometric](https://github.com/alvinometric))
+- Hichem Fantar ([@hichemfantar](https://github.com/hichemfantar))
+- Ivan Cheban ([@ivancheban](https://github.com/ivancheban))
+- Jake Boone ([@jakeboone02](https://github.com/jakeboone02))
+- Jan Aukema ([@janaukema](https://github.com/janaukema))
+- Lehoczky Zoltán ([@Lehoczky](https://github.com/Lehoczky))
+- Lin Huang ([@codimiracle](https://github.com/codimiracle))
+- Pierre Millot ([@millotp](https://github.com/millotp))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Taylor Reece ([@taylorreece](https://github.com/taylorreece))
+- Waldir Pimenta ([@waldyrious](https://github.com/waldyrious))
+- William Black ([@WillBlack403](https://github.com/WillBlack403))
+- Zed Spencer-Milnes ([@GingerGeek](https://github.com/GingerGeek))
+- Zen ([@effozen](https://github.com/effozen))
+
+## 3.6.3 (2024-11-22)
+
+#### :bug: Bug Fix
+
+- `docusaurus`
+  - [#10712](https://github.com/facebook/docusaurus/pull/10712) fix(core): disable Rspack incremental in dev ([@slorber](https://github.com/slorber))
+
+#### Committers: 1
+
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
 ## 3.6.2 (2024-11-19)
 
 #### :bug: Bug Fix

admin/new.docusaurus.io/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new.docusaurus.io",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "start": "npx --package netlify-cli netlify dev"

admin/scripts/test-release.sh

@@ -5,7 +5,9 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-set -euo pipefail
+set -xeuo pipefail
+
+rm -rf ../test-website
 
 CUSTOM_REGISTRY_URL="http://localhost:4873"
 NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version")-NEW"
@@ -52,7 +54,8 @@ git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 cd ..
 
 # Build skeleton website with new version
-npm_config_registry="$CUSTOM_REGISTRY_URL" npx create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+npm_config_registry="$CUSTOM_REGISTRY_URL" npx --yes --loglevel silly create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+
 
 # Stop Docker container
 if [[ -z "${KEEP_CONTAINER:-true}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then

admin/test-bad-package/README.mdx

@@ -12,7 +12,7 @@ import {version as ReactVersion} from 'react';
 import {version as ReactDOMVersion} from 'react-dom';
 
 export function TestComponent() {
-  const expectedVersion = 18;
+  const expectedVersion = 19;
   if (!ReactVersion.startsWith(`${expectedVersion}`)) {
     throw new Error(
       `'test-bad-package/README.mdx' is rendered with bad React version: ${ReactVersion}`,

admin/test-bad-package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "test-bad-package",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "private": true,
   "dependencies": {
     "@mdx-js/react": "1.0.1",

argos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argos",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Argos visual diff tests",
   "license": "MIT",
   "private": true,

argos/tests/screenshot.spec.ts

@@ -55,7 +55,6 @@ function isBlacklisted(pathname: string) {
     '/tests/pages/react-18',
     // Flaky because of hydration error
     '/tests/blog/archive',
-    '/tests/docs/tests/custom-props',
     '/tests/pages/code-block-tests',
     '/tests/pages/embeds',
     // Flaky because of hydration error with docusaurus serve + .html
@@ -131,23 +130,18 @@ function throwOnConsole(page: Page) {
   const typesToCheck = ['error', 'warning'];
 
   const ignoreMessages = [
-    // This mismatch warning looks like a React 18 bug to me
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s className "null" ""',
-
     // TODO this fetch error message is unexpected and should be fixed
     //  it's already happening in main branch
     'Failed to load resource: the server responded with a status of 404 (Not Found)',
 
-    // TODO looks like a legit hydration bug to fix
+    // TODO legit hydration bugs to fix on embeds of /docs/styling-layout
-    // on /blog/releases/2.4
+    //  useLocation() returns window.search/hash immediately :s
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-theme=light"',
+    '/docs/configuration?docusaurus-theme=light',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-theme=dark"',
+    '/docs/configuration?docusaurus-theme=dark',
-    // on /blog/releases/3.0
+
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-data-navbar=false&docusaurus-data-red-border"',
+    // Warning because react-live not supporting React automatic JSX runtime
-    // on /docs/styling-layout
+    // See https://github.com/FormidableLabs/react-live/issues/405
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-data-navbar=false&docusaurus-data-red-border"',
+    'Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs/configuration" "/docs/configuration?docusaurus-theme=light"',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs/configuration" "/docs/configuration?docusaurus-theme=dark"',
 
     // TODO weird problem related to KaTeX fonts refusing to decode?
     //  on /docs/markdown-features/math-equations

examples/README.md

@@ -2,7 +2,7 @@
 
 These example projects are generated with the init CLI:
 
-```
+```bash
 npx @docusaurus/init@latest init examples/<templateName> <templateName>`
 ```
 

examples/classic-typescript/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

examples/classic-typescript/package.json

@@ -16,18 +16,18 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.0",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/preset-classic": "3.6.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
+    "react": "^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.0",
+    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/tsconfig": "3.6.0",
+    "@docusaurus/tsconfig": "3.7.0",
-    "@docusaurus/types": "3.6.0",
+    "@docusaurus/types": "3.7.0",
     "typescript": "~5.6.2"
   },
   "browserslist": {

examples/classic-typescript/src/components/HomepageFeatures/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
@@ -5,7 +6,7 @@ import styles from './styles.module.css';
 type FeatureItem = {
   title: string;
   Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
+  description: ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
@@ -55,7 +56,7 @@ function Feature({title, Svg, description}: FeatureItem) {
   );
 }
 
-export default function HomepageFeatures(): JSX.Element {
+export default function HomepageFeatures(): ReactNode {
   return (
     <section className={styles.features}>
       <div className="container">

examples/classic-typescript/src/pages/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -28,7 +29,7 @@ function HomepageHeader() {
   );
 }
 
-export default function Home(): JSX.Element {
+export default function Home(): ReactNode {
   const {siteConfig} = useDocusaurusContext();
   return (
     <Layout

examples/classic-typescript/tsconfig.json

@@ -3,5 +3,6 @@
   "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
-  }
+  },
+  "exclude": [".docusaurus", "build"]
 }

examples/classic/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

examples/classic/package.json

@@ -15,17 +15,17 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.0",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/preset-classic": "3.6.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
+    "react": "^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.0",
+    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/types": "3.6.0"
+    "@docusaurus/types": "3.7.0"
   },
   "browserslist": {
     "production": [

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.2",
+  "version": "3.7.0",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "useNx": false,

package.json

@@ -50,7 +50,7 @@
     "canary:bumpVersion": "yarn lerna version `yarn --silent canary:version` --exact --no-push --yes",
     "canary:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "changelog": "lerna-changelog",
-    "postinstall": "yarn lock:update && yarn build:packages",
+    "postinstall": "patch-package && yarn lock:update && yarn build:packages",
     "prepare": "husky install",
     "format": "prettier --write .",
     "format:diff": "prettier --list-different .",
@@ -112,10 +112,11 @@
     "lint-staged": "~13.2.3",
     "lockfile-lint": "^4.14.0",
     "npm-run-all": "^4.1.5",
+    "patch-package": "^8.0.0",
+    "postinstall-postinstall": "^2.1.0",
     "prettier": "^2.8.8",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "react-helmet-async": "^1.3.0",
     "react-test-renderer": "^18.0.0",
     "rimraf": "^3.0.2",
     "sharp": "^0.32.3",
@@ -123,6 +124,7 @@
     "stylelint": "^14.16.1",
     "stylelint-config-prettier": "^9.0.5",
     "stylelint-config-standard": "^29.0.0",
-    "typescript": "~5.6.2"
+    "typescript": "~5.7.2"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,8 +22,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
     "commander": "^5.1.0",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",

packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts

@@ -9,6 +9,11 @@ const config: Config = {
   tagline: 'Dinosaurs are cool',
   favicon: 'img/favicon.ico',
 
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
   // Set the production url of your site here
   url: 'https://your-docusaurus-site.example.com',
   // Set the /<baseUrl>/ pathname under which your site is served

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-typescript-template",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,18 +15,18 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/preset-classic": "3.6.2",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
+    "react": "^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.2",
+    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/tsconfig": "3.6.2",
+    "@docusaurus/tsconfig": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
     "typescript": "~5.6.2"
   },
   "browserslist": {

packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
@@ -5,7 +6,7 @@ import styles from './styles.module.css';
 type FeatureItem = {
   title: string;
   Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
+  description: ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
@@ -55,7 +56,7 @@ function Feature({title, Svg, description}: FeatureItem) {
   );
 }
 
-export default function HomepageFeatures(): JSX.Element {
+export default function HomepageFeatures(): ReactNode {
   return (
     <section className={styles.features}>
       <div className="container">

packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -28,7 +29,7 @@ function HomepageHeader() {
   );
 }
 
-export default function Home(): JSX.Element {
+export default function Home(): ReactNode {
   const {siteConfig} = useDocusaurusContext();
   return (
     <Layout

packages/create-docusaurus/templates/classic/docusaurus.config.js

@@ -14,6 +14,11 @@ const config = {
   tagline: 'Dinosaurs are cool',
   favicon: 'img/favicon.ico',
 
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
   // Set the production url of your site here
   url: 'https://your-docusaurus-site.example.com',
   // Set the /<baseUrl>/ pathname under which your site is served

packages/create-docusaurus/templates/classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-template",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,17 +14,17 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/preset-classic": "3.6.2",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
+    "react": "^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.2",
+    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/types": "3.6.2"
+    "@docusaurus/types": "3.7.0"
   },
   "browserslist": {
     "production": [

packages/create-docusaurus/templates/shared/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

packages/create-docusaurus/templates/shared/blog/authors.yml

@@ -1,12 +1,14 @@
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
-  url: https://github.com/yangshun
+  url: https://linkedin.com/in/yangshun
   image_url: https://github.com/yangshun.png
   page: true
   socials:
     x: yangshunz
+    linkedin: yangshun
     github: yangshun
+    newsletter: https://www.greatfrontend.com
 
 slorber:
   name: Sébastien Lorber

packages/docusaurus-babel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/babel",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docusaurus package for Babel-related utils.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -38,8 +38,8 @@
     "@babel/runtime": "^7.25.9",
     "@babel/runtime-corejs3": "^7.25.9",
     "@babel/traverse": "^7.25.9",
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
     "babel-plugin-dynamic-import-node": "^2.3.3",
     "fs-extra": "^11.1.1",
     "tslib": "^2.6.0"

packages/docusaurus-bundler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/bundler",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docusaurus util package to abstract the current bundler.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,11 +19,11 @@
   "license": "MIT",
   "dependencies": {
     "@babel/core": "^7.25.9",
-    "@docusaurus/babel": "3.6.2",
+    "@docusaurus/babel": "3.7.0",
-    "@docusaurus/cssnano-preset": "3.6.2",
+    "@docusaurus/cssnano-preset": "3.7.0",
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
     "babel-loader": "^9.2.1",
     "clean-css": "^5.3.2",
     "copy-webpack-plugin": "^11.0.0",

packages/docusaurus-bundler/src/minifyHtml.ts

@@ -47,9 +47,13 @@ async function getTerserMinifier(): Promise<HtmlMinifier> {
     minify: async function minifyHtmlWithTerser(html) {
       try {
         const code = await terserHtmlMinifier(html, {
+          // When enabled => React hydration errors
           removeComments: false,
-          removeRedundantAttributes: true,
+          removeRedundantAttributes: false,
-          removeEmptyAttributes: true,
+          removeEmptyAttributes: false,
+          sortAttributes: false,
+          sortClassName: false,
+
           removeScriptTypeAttributes: true,
           removeStyleLinkTypeAttributes: true,
           useShortDoctype: true,
@@ -84,8 +88,13 @@ async function getSwcMinifier(): Promise<HtmlMinifier> {
           sortSpaceSeparatedAttributeValues: false,
           sortAttributes: false,
 
-          removeRedundantAttributes: 'all',
+          // When enabled => hydration error for className={"yt-lite "}
-          removeEmptyAttributes: true,
+          normalizeAttributes: false,
+          // When enabled => hydration error for className=""
+          removeEmptyAttributes: false,
+          // When enabled => hydration error for <a target="_self">
+          removeRedundantAttributes: 'none',
+
           minifyJs: true,
           minifyJson: true,
           minifyCss: true,

packages/docusaurus-cssnano-preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/cssnano-preset",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Advanced cssnano preset for maximum optimization.",
   "main": "lib/index.js",
   "license": "MIT",

packages/docusaurus-faster/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/faster",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docusaurus experimental package exposing new modern dependencies to make the build faster.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@rspack/core": "^1.1.1",
+    "@rspack/core": "^1.2.5",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",

packages/docusaurus-logger/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/logger",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "An encapsulated logger for semantically formatting console messages.",
   "main": "./lib/index.js",
   "repository": {

packages/docusaurus-logger/src/perfLogger.ts

@@ -114,12 +114,24 @@ function createPerfLogger(): PerfLoggerAPI {
       },
     });
 
-  const end: PerfLoggerAPI['end'] = (label) => {
+  const readMark = (label: string) => {
-    const {
+    const startMark = performance.getEntriesByName(
-      duration,
+      label,
-      detail: {memoryUsage},
+      'mark',
-    } = performance.measure(label);
+    )?.[0] as PerformanceMark;
+    if (!startMark) {
+      throw new Error(`No performance start mark for label=${label}`);
+    }
     performance.clearMarks(label);
+    return startMark;
+  };
+
+  const end: PerfLoggerAPI['end'] = (label) => {
+    const startMark = readMark(label);
+    const duration = performance.now() - startMark.startTime;
+    const {
+      detail: {memoryUsage},
+    } = startMark;
     printPerfLog({
       label: applyParentPrefix(label),
       duration,

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.2",
+    "@docusaurus/utils-validation": "3.7.0",
     "@mdx-js/mdx": "^3.0.0",
     "@slorber/remark-comment": "^1.0.0",
     "escape-html": "^1.0.3",
@@ -44,7 +44,7 @@
     "webpack": "^5.88.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",
@@ -58,8 +58,8 @@
     "unist-util-remove-position": "^5.0.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-mdx-loader/src/index.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type {ReactNode} from 'react';
+
 import {mdxLoader} from './loader';
 
 import type {TOCItem as TOCItemImported} from './remark/toc/types';
@@ -34,7 +36,7 @@ export type LoadedMDXContent<FrontMatter, Metadata, Assets = undefined> = {
    * in priority.
    */
   readonly assets: Assets;
-  (): JSX.Element;
+  (): ReactNode;
 };
 
 export type {MDXPlugin} from './loader';

packages/docusaurus-mdx-loader/src/loader.ts

@@ -218,6 +218,7 @@ export async function mdxLoader(
   const compilerName = getWebpackLoaderCompilerName(this);
   const callback = this.async();
   const options: Options = this.getOptions();
+  options.dependencies?.forEach(this.addDependency);
   try {
     const result = await loadMDXWithCaching({
       resource: this.resource,

packages/docusaurus-mdx-loader/src/options.ts

@@ -11,6 +11,8 @@ import type {ResolveMarkdownLink} from './remark/resolveMarkdownLinks';
 import type {PromiseWithResolvers} from './utils';
 
 export type Options = Partial<MDXOptions> & {
+  dependencies?: string[];
+
   markdownConfig: MarkdownConfig;
   staticDirs: string[];
   siteDir: string;

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/img.md

@@ -29,3 +29,13 @@ in paragraph ![img](static/img.png)
 ```md
 ![img](./static/img.png)
 ```
+
+## Images with spaces
+
+![img](</img with spaces.png>)
+
+![img](<@site/static/img with spaces.png>)
+
+![img](</img with one encoded%2520space.png>)
+
+![img](<@site/static/img with one encoded%2520space.png>)

packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__snapshots__/index.test.ts.snap

@@ -48,5 +48,15 @@ in paragraph <img alt="img" src={require("!<PROJECT_ROOT>/node_modules/url-loade
 \`\`\`md
 ![img](./static/img.png)
 \`\`\`
+
+## Images with spaces
+
+<img alt="img" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/img with spaces.png").default} width="200" height="200" />
+
+<img alt="img" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/img with spaces.png").default} width="200" height="200" />
+
+<img alt="img" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/img with one encoded%20space.png").default} width="200" height="200" />
+
+<img alt="img" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/img with one encoded%20space.png").default} width="200" height="200" />
 "
 `;

packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts

@@ -98,6 +98,7 @@ async function toImageRequireNode(
       });
     }
   } catch (err) {
+    console.error(err);
     // Workaround for https://github.com/yarnpkg/berry/pull/3889#issuecomment-1034469784
     // TODO remove this check once fixed in Yarn PnP
     if (!process.versions.pnp) {
@@ -152,10 +153,7 @@ async function getImageAbsolutePath(
     return imageFilePath;
   }
   // relative paths are resolved against the source file's folder
-  const imageFilePath = path.join(
+  const imageFilePath = path.join(path.dirname(filePath), imagePath);
-    path.dirname(filePath),
-    decodeURIComponent(imagePath),
-  );
   await ensureImageFileExist(imageFilePath, filePath);
   return imageFilePath;
 }
@@ -180,9 +178,14 @@ async function processImageNode(target: Target, context: Context) {
     return;
   }
 
+  // We decode it first because Node Url.pathname is always encoded
+  // while the image file-system path are not.
+  // See https://github.com/facebook/docusaurus/discussions/10720
+  const decodedPathname = decodeURIComponent(parsedUrl.pathname);
+
   // We try to convert image urls without protocol to images with require calls
   // going through webpack ensures that image assets exist at build time
-  const imagePath = await getImageAbsolutePath(parsedUrl.pathname, context);
+  const imagePath = await getImageAbsolutePath(decodedPathname, context);
   await toImageRequireNode(target, imagePath, context);
 }
 

packages/docusaurus-module-type-aliases/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/module-type-aliases",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docusaurus module type aliases.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -12,12 +12,12 @@
     "directory": "packages/docusaurus-module-type-aliases"
   },
   "dependencies": {
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",
     "@types/react-router-dom": "*",
-    "react-helmet-async": "*",
+    "react-helmet-async": "npm:@slorber/react-helmet-async@*",
     "react-loadable": "npm:@docusaurus/react-loadable@6.0.0"
   },
   "peerDependencies": {

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -84,10 +84,11 @@ declare module '@theme-original/*';
 declare module '@theme-init/*';
 
 declare module '@theme/Error' {
+  import type {ReactNode} from 'react';
   import type {FallbackParams} from '@docusaurus/ErrorBoundary';
 
   export interface Props extends FallbackParams {}
-  export default function Error(props: Props): JSX.Element;
+  export default function Error(props: Props): ReactNode;
 }
 
 declare module '@theme/Layout' {
@@ -96,17 +97,20 @@ declare module '@theme/Layout' {
   export interface Props {
     readonly children?: ReactNode;
   }
-  export default function Layout(props: Props): JSX.Element;
+  export default function Layout(props: Props): ReactNode;
 }
 
 declare module '@theme/Loading' {
+  import type {ReactNode} from 'react';
   import type {LoadingComponentProps} from 'react-loadable';
 
-  export default function Loading(props: LoadingComponentProps): JSX.Element;
+  export default function Loading(props: LoadingComponentProps): ReactNode;
 }
 
 declare module '@theme/NotFound' {
-  export default function NotFound(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function NotFound(): ReactNode;
 }
 
 declare module '@theme/Root' {
@@ -115,11 +119,13 @@ declare module '@theme/Root' {
   export interface Props {
     readonly children: ReactNode;
   }
-  export default function Root({children}: Props): JSX.Element;
+  export default function Root({children}: Props): ReactNode;
 }
 
 declare module '@theme/SiteMetadata' {
-  export default function SiteMetadata(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function SiteMetadata(): ReactNode;
 }
 
 declare module '@docusaurus/constants' {
@@ -134,13 +140,13 @@ declare module '@docusaurus/ErrorBoundary' {
     readonly tryAgain: () => void;
   };
 
-  export type FallbackFunction = (params: FallbackParams) => JSX.Element;
+  export type FallbackFunction = (params: FallbackParams) => ReactNode;
 
   export interface Props {
     readonly fallback?: FallbackFunction;
     readonly children: ReactNode;
   }
-  export default function ErrorBoundary(props: Props): JSX.Element;
+  export default function ErrorBoundary(props: Props): ReactNode;
 }
 
 declare module '@docusaurus/Head' {
@@ -149,11 +155,11 @@ declare module '@docusaurus/Head' {
 
   export type Props = HelmetProps & {children: ReactNode};
 
-  export default function Head(props: Props): JSX.Element;
+  export default function Head(props: Props): ReactNode;
 }
 
 declare module '@docusaurus/Link' {
-  import type {CSSProperties, ComponentProps} from 'react';
+  import type {CSSProperties, ComponentProps, ReactNode} from 'react';
   import type {NavLinkProps as RRNavLinkProps} from 'react-router-dom';
 
   type NavLinkProps = Partial<RRNavLinkProps>;
@@ -169,7 +175,7 @@ declare module '@docusaurus/Link' {
       /** Escape hatch in case broken links check doesn't make sense. */
       readonly 'data-noBrokenLinkCheck'?: boolean;
     };
-  export default function Link(props: Props): JSX.Element;
+  export default function Link(props: Props): ReactNode;
 }
 
 declare module '@docusaurus/Interpolate' {
@@ -203,7 +209,7 @@ declare module '@docusaurus/Interpolate' {
 
   export default function Interpolate<Str extends string>(
     props: InterpolateProps<Str>,
-  ): JSX.Element;
+  ): ReactNode;
 }
 
 declare module '@docusaurus/Translate' {
@@ -241,7 +247,7 @@ declare module '@docusaurus/Translate' {
 
   export default function Translate<Str extends string>(
     props: TranslateProps<Str>,
-  ): JSX.Element;
+  ): ReactNode;
 }
 
 declare module '@docusaurus/router' {
@@ -318,11 +324,13 @@ declare module '@docusaurus/ComponentCreator' {
 }
 
 declare module '@docusaurus/BrowserOnly' {
+  import type {ReactNode} from 'react';
+
   export interface Props {
-    readonly children?: () => JSX.Element;
+    readonly children?: () => ReactNode;
-    readonly fallback?: JSX.Element;
+    readonly fallback?: ReactNode;
   }
-  export default function BrowserOnly(props: Props): JSX.Element | null;
+  export default function BrowserOnly(props: Props): ReactNode | null;
 }
 
 declare module '@docusaurus/isInternalUrl' {
@@ -369,6 +377,9 @@ declare module '@docusaurus/useGlobalData' {
   export default function useGlobalData(): GlobalData;
 }
 
+// TODO find a way to move this ambient type to the SVGR plugin?
+//  unfortunately looks complicated in practice
+//  see https://x.com/sebastienlorber/status/1859543512661832053
 declare module '*.svg' {
   import type {ComponentType, SVGProps} from 'react';
 

packages/docusaurus-plugin-client-redirects/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-client-redirects",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Client redirects plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,22 +18,22 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-common": "3.6.2",
+    "@docusaurus/utils-common": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.2",
+    "@docusaurus/utils-validation": "3.7.0",
     "eta": "^2.2.0",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "tslib": "^2.6.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.6.2"
+    "@docusaurus/types": "3.7.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-blog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,19 +31,20 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/mdx-loader": "3.6.2",
+    "@docusaurus/mdx-loader": "3.7.0",
-    "@docusaurus/theme-common": "3.6.2",
+    "@docusaurus/theme-common": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-common": "3.6.2",
+    "@docusaurus/utils-common": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.2",
+    "@docusaurus/utils-validation": "3.7.0",
     "cheerio": "1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "reading-time": "^1.5.0",
+    "schema-dts": "^1.1.2",
     "srcset": "^4.0.0",
     "tslib": "^2.6.0",
     "unist-util-visit": "^5.0.0",
@@ -52,8 +53,8 @@
   },
   "peerDependencies": {
     "@docusaurus/plugin-content-docs": "*",
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-blog/src/__tests__/authorsSocials.test.ts

@@ -15,14 +15,27 @@ describe('normalizeSocials', () => {
       linkedin: 'ozakione',
       github: 'ozakione',
       stackoverflow: 'ozakione',
+      threads: 'gingergeekuk',
+      bluesky: 'gingergeek.co.uk',
+      instagram: 'thisweekinreact',
+      twitch: 'gingergeek',
+      youtube: 'gingergeekuk',
+      mastodon: 'Mastodon',
     };
 
+    // eslint-disable-next-line jest/no-large-snapshots
     expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
       {
+        "bluesky": "https://bsky.app/profile/gingergeek.co.uk",
         "github": "https://github.com/ozakione",
+        "instagram": "https://www.instagram.com/thisweekinreact",
         "linkedin": "https://www.linkedin.com/in/ozakione/",
+        "mastodon": "https://mastodon.social/@Mastodon",
         "stackoverflow": "https://stackoverflow.com/users/ozakione",
+        "threads": "https://www.threads.net/@gingergeekuk",
+        "twitch": "https://twitch.tv/gingergeek",
         "twitter": "https://twitter.com/ozakione",
+        "youtube": "https://youtube.com/@gingergeekuk",
       }
     `);
   });
@@ -33,13 +46,19 @@ describe('normalizeSocials', () => {
       linkedIn: 'ozakione',
       gitHub: 'ozakione',
       STACKoverflow: 'ozakione',
+      instaGRam: 'thisweekinreact',
+      BLUESKY: 'gingergeek.co.uk',
+      tHrEaDs: 'gingergeekuk',
     };
 
     expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
       {
+        "bluesky": "https://bsky.app/profile/gingergeek.co.uk",
         "github": "https://github.com/ozakione",
+        "instagram": "https://www.instagram.com/thisweekinreact",
         "linkedin": "https://www.linkedin.com/in/ozakione/",
         "stackoverflow": "https://stackoverflow.com/users/ozakione",
+        "threads": "https://www.threads.net/@gingergeekuk",
         "twitter": "https://twitter.com/ozakione",
       }
     `);
@@ -62,12 +81,14 @@ describe('normalizeSocials', () => {
       linkedin: 'ozakione',
       github: 'https://github.com/ozakione',
       stackoverflow: 'https://stackoverflow.com/ozakione',
+      mastodon: 'https://hachyderm.io/@hachyderm',
     };
 
     expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
       {
         "github": "https://github.com/ozakione",
         "linkedin": "https://www.linkedin.com/in/ozakione/",
+        "mastodon": "https://hachyderm.io/@hachyderm",
         "stackoverflow": "https://stackoverflow.com/ozakione",
         "twitter": "https://twitter.com/ozakione",
       }

packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts

@@ -79,6 +79,7 @@ describe('validateBlogPostFrontMatter description', () => {
     prefix: 'description',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+      {description: undefined},
       {description: ''},
       {description: 'description'},
     ],
@@ -90,6 +91,7 @@ describe('validateBlogPostFrontMatter title', () => {
     prefix: 'title',
     validFrontMatters: [
       // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+      {title: undefined},
       {title: ''},
       {title: 'title'},
     ],
@@ -103,7 +105,11 @@ describe('validateBlogPostFrontMatter title', () => {
 describe('validateBlogPostFrontMatter title_meta', () => {
   testField({
     prefix: 'title_meta',
-    validFrontMatters: [{title: ''}, {title_meta: 'title'}],
+    validFrontMatters: [
+      {title_meta: undefined},
+      {title_meta: ''},
+      {title_meta: 'title'},
+    ],
     invalidFrontMatters: [
       [{title_meta: null}, 'must be a string'],
       [{title_meta: false}, 'must be a string'],
@@ -111,6 +117,21 @@ describe('validateBlogPostFrontMatter title_meta', () => {
   });
 });
 
+describe('validateBlogPostFrontMatter sidebar_label', () => {
+  testField({
+    prefix: 'title_meta',
+    validFrontMatters: [
+      {sidebar_label: undefined},
+      {sidebar_label: ''},
+      {sidebar_label: 'title'},
+    ],
+    invalidFrontMatters: [
+      [{sidebar_label: null}, 'must be a string'],
+      [{sidebar_label: false}, 'must be a string'],
+    ],
+  });
+});
+
 describe('validateBlogPostFrontMatter id', () => {
   testField({
     prefix: 'id',

packages/docusaurus-plugin-content-blog/src/__tests__/props.test.ts

@@ -94,7 +94,7 @@ describe('toBlogSidebarProp', () => {
           permalink: '/blog/blog-2',
           unlisted: true,
           date: '2024-01-01',
-          frontMatter: {hello: 'world'},
+          frontMatter: {hello: 'world', sidebar_label: 'title 2 (custom)'},
           tags: [{label: 'tag1', permalink: '/tag1', inline: false}],
         },
       }),
@@ -117,7 +117,7 @@ describe('toBlogSidebarProp', () => {
           {
             "date": "2024-01-01",
             "permalink": "/blog/blog-2",
-            "title": "title 2",
+            "title": "title 2 (custom)",
             "unlisted": true,
           },
         ],

packages/docusaurus-plugin-content-blog/src/authorsSocials.ts

@@ -21,6 +21,12 @@ export const AuthorSocialsSchema = Joi.object<AuthorSocials>({
     .try(Joi.number(), Joi.string())
     .custom((val) => String(val)),
   x: Joi.string(),
+  bluesky: Joi.string(),
+  instagram: Joi.string(),
+  threads: Joi.string(),
+  mastodon: Joi.string(),
+  twitch: Joi.string(),
+  youtube: Joi.string(),
 }).unknown();
 
 type PredefinedPlatformNormalizer = (value: string) => string;
@@ -35,6 +41,12 @@ const PredefinedPlatformNormalizers: Record<
   linkedin: (handle: string) => `https://www.linkedin.com/in/${handle}/`,
   stackoverflow: (userId: string) =>
     `https://stackoverflow.com/users/${userId}`,
+  bluesky: (handle: string) => `https://bsky.app/profile/${handle}`,
+  instagram: (handle: string) => `https://www.instagram.com/${handle}`,
+  threads: (handle: string) => `https://www.threads.net/@${handle}`,
+  mastodon: (handle: string) => `https://mastodon.social/@${handle}`, // can be in format user@other.server and it will redirect if needed
+  twitch: (handle: string) => `https://twitch.tv/${handle}`,
+  youtube: (handle: string) => `https://youtube.com/@${handle}`, // https://support.google.com/youtube/answer/6180214?hl=en
 };
 
 type SocialEntry = [string, string];

packages/docusaurus-plugin-content-blog/src/client/contexts.tsx

@@ -74,7 +74,7 @@ export function BlogPostProvider({
   children: ReactNode;
   content: PropBlogPostContent;
   isBlogPostPage?: boolean;
-}): JSX.Element {
+}): ReactNode {
   const contextValue = useContextValue({content, isBlogPostPage});
   return <Context.Provider value={contextValue}>{children}</Context.Provider>;
 }

packages/docusaurus-plugin-content-blog/src/frontMatter.ts

@@ -33,7 +33,8 @@ const FrontMatterAuthorErrorMessage =
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
-  title_meta: Joi.string(),
+  title_meta: Joi.string().allow(''),
+  sidebar_label: Joi.string().allow(''),
   description: Joi.string().allow(''),
   tags: FrontMatterTagsSchema,
   date: Joi.date().raw(),

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -16,7 +16,12 @@ declare module '@docusaurus/plugin-content-blog' {
     FrontMatterLastUpdate,
     TagsPluginOptions,
   } from '@docusaurus/utils';
-  import type {DocusaurusConfig, Plugin, LoadContext} from '@docusaurus/types';
+  import type {
+    DocusaurusConfig,
+    Plugin,
+    LoadContext,
+    OptionValidationContext,
+  } from '@docusaurus/types';
   import type {Item as FeedItem} from 'feed';
   import type {Overwrite} from 'utility-types';
 
@@ -46,7 +51,13 @@ declare module '@docusaurus/plugin-content-blog' {
     | 'github'
     | 'linkedin'
     | 'stackoverflow'
-    | 'x';
+    | 'x'
+    | 'bluesky'
+    | 'instagram'
+    | 'threads'
+    | 'mastodon'
+    | 'youtube'
+    | 'twitch';
 
   /**
    * Social platforms of the author.
@@ -145,7 +156,6 @@ declare module '@docusaurus/plugin-content-blog' {
     title?: string;
     /**
      * Will be used for SEO page metadata and override BlogPostMetadata.title.
-     * @see {@link BlogPostMetadata.title_meta}
      */
     title_meta?: string;
     /**
@@ -153,6 +163,10 @@ declare module '@docusaurus/plugin-content-blog' {
      * @see {@link BlogPostMetadata.description}
      */
     description?: string;
+    /**
+     * Will override the default excerpt.
+     */
+    sidebar_label?: string;
     /**
      * Front matter tags, unnormalized.
      * @see {@link BlogPostMetadata.tags}
@@ -657,9 +671,14 @@ declare module '@docusaurus/plugin-content-blog' {
     context: LoadContext,
     options: PluginOptions,
   ): Promise<Plugin<BlogContent>>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
 }
 
 declare module '@theme/BlogPostPage' {
+  import type {ReactNode} from 'react';
   import type {
     BlogPostFrontMatter,
     BlogSidebar,
@@ -680,18 +699,23 @@ declare module '@theme/BlogPostPage' {
     readonly blogMetadata: BlogMetadata;
   }
 
-  export default function BlogPostPage(props: Props): JSX.Element;
+  export default function BlogPostPage(props: Props): ReactNode;
 }
 
 declare module '@theme/BlogPostPage/Metadata' {
-  export default function BlogPostPageMetadata(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function BlogPostPageMetadata(): ReactNode;
 }
 
 declare module '@theme/BlogPostPage/StructuredData' {
-  export default function BlogPostStructuredData(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function BlogPostStructuredData(): ReactNode;
 }
 
 declare module '@theme/BlogListPage' {
+  import type {ReactNode} from 'react';
   import type {Content} from '@theme/BlogPostPage';
   import type {
     BlogSidebar,
@@ -710,10 +734,11 @@ declare module '@theme/BlogListPage' {
     readonly items: readonly {readonly content: Content}[];
   }
 
-  export default function BlogListPage(props: Props): JSX.Element;
+  export default function BlogListPage(props: Props): ReactNode;
 }
 
 declare module '@theme/BlogListPage/StructuredData' {
+  import type {ReactNode} from 'react';
   import type {Content} from '@theme/BlogPostPage';
   import type {
     BlogSidebar,
@@ -732,10 +757,11 @@ declare module '@theme/BlogListPage/StructuredData' {
     readonly items: readonly {readonly content: Content}[];
   }
 
-  export default function BlogListPageStructuredData(props: Props): JSX.Element;
+  export default function BlogListPageStructuredData(props: Props): ReactNode;
 }
 
 declare module '@theme/BlogTagsListPage' {
+  import type {ReactNode} from 'react';
   import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
   import type {TagsListItem} from '@docusaurus/utils';
 
@@ -746,10 +772,11 @@ declare module '@theme/BlogTagsListPage' {
     readonly tags: TagsListItem[];
   }
 
-  export default function BlogTagsListPage(props: Props): JSX.Element;
+  export default function BlogTagsListPage(props: Props): ReactNode;
 }
 
 declare module '@theme/Blog/Pages/BlogAuthorsListPage' {
+  import type {ReactNode} from 'react';
   import type {
     AuthorItemProp,
     BlogSidebar,
@@ -762,10 +789,11 @@ declare module '@theme/Blog/Pages/BlogAuthorsListPage' {
     readonly authors: AuthorItemProp[];
   }
 
-  export default function BlogAuthorsListPage(props: Props): JSX.Element;
+  export default function BlogAuthorsListPage(props: Props): ReactNode;
 }
 
 declare module '@theme/Blog/Pages/BlogAuthorsPostsPage' {
+  import type {ReactNode} from 'react';
   import type {Content} from '@theme/BlogPostPage';
   import type {
     AuthorItemProp,
@@ -787,10 +815,11 @@ declare module '@theme/Blog/Pages/BlogAuthorsPostsPage' {
     readonly items: readonly {readonly content: Content}[];
   }
 
-  export default function BlogAuthorsPostsPage(props: Props): JSX.Element;
+  export default function BlogAuthorsPostsPage(props: Props): ReactNode;
 }
 
 declare module '@theme/BlogTagsPostsPage' {
+  import type {ReactNode} from 'react';
   import type {Content} from '@theme/BlogPostPage';
   import type {
     BlogSidebar,
@@ -812,10 +841,11 @@ declare module '@theme/BlogTagsPostsPage' {
     readonly items: readonly {readonly content: Content}[];
   }
 
-  export default function BlogTagsPostsPage(props: Props): JSX.Element;
+  export default function BlogTagsPostsPage(props: Props): ReactNode;
 }
 
 declare module '@theme/BlogArchivePage' {
+  import type {ReactNode} from 'react';
   import type {Content} from '@theme/BlogPostPage';
 
   /** We may add extra metadata or prune some metadata from here */
@@ -829,5 +859,5 @@ declare module '@theme/BlogArchivePage' {
     };
   }
 
-  export default function BlogArchivePage(props: Props): JSX.Element;
+  export default function BlogArchivePage(props: Props): ReactNode;
 }

packages/docusaurus-plugin-content-blog/src/props.ts

@@ -65,7 +65,8 @@ export function toBlogSidebarProp({
   return {
     title: blogSidebarTitle,
     items: blogPosts.map((blogPost) => ({
-      title: blogPost.metadata.title,
+      title:
+        blogPost.metadata.frontMatter.sidebar_label ?? blogPost.metadata.title,
       permalink: blogPost.metadata.permalink,
       unlisted: blogPost.metadata.unlisted,
       date: blogPost.metadata.date,

packages/docusaurus-plugin-content-docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,20 +35,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/logger": "3.6.2",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/mdx-loader": "3.6.2",
+    "@docusaurus/mdx-loader": "3.7.0",
-    "@docusaurus/module-type-aliases": "3.6.2",
+    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/theme-common": "3.6.2",
+    "@docusaurus/theme-common": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-common": "3.6.2",
+    "@docusaurus/utils-common": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.2",
+    "@docusaurus/utils-validation": "3.7.0",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
+    "schema-dts": "^1.1.2",
     "tslib": "^2.6.0",
     "utility-types": "^3.10.0",
     "webpack": "^5.88.1"
@@ -61,8 +62,8 @@
     "shelljs": "^0.8.5"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json

@@ -0,0 +1,3 @@
+{
+  "some.key": "some translation"
+}

packages/docusaurus-plugin-content-docs/src/cli.ts

@@ -14,6 +14,7 @@ import {
   getVersionDocsDirPath,
   getVersionSidebarsPath,
   getDocsDirPathLocalized,
+  getPluginDirPathLocalized,
   readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
@@ -123,6 +124,23 @@ async function cliDocsVersionCommand(
               versionName: version,
             });
       await fs.copy(docsDir, newVersionDir);
+
+      // Copy version JSON translation file for this locale
+      // i18n/<l>/docusaurus-plugin-content-docs/current.json => version-v1.json
+      // See https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#translation-files-location
+      if (locale !== i18n.defaultLocale) {
+        const dir = getPluginDirPathLocalized({
+          localizationDir,
+          pluginId,
+        });
+        const sourceFile = path.join(dir, 'current.json');
+        const dest = path.join(dir, `version-${version}.json`);
+        if (await fs.pathExists(sourceFile)) {
+          await fs.copy(sourceFile, dest);
+        } else {
+          logger.warn`${pluginIdLogPrefix}: i18n translation file does not exist in path=${sourceFile}. Skipping.`;
+        }
+      }
     }),
   );
 

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsUtils.test.tsx

@@ -15,6 +15,7 @@ import {
   useDocById,
   findSidebarCategory,
   useCurrentSidebarCategory,
+  useCurrentSidebarSiblings,
   useSidebarBreadcrumbs,
   isVisibleSidebarItem,
 } from '../docsUtils';
@@ -440,6 +441,7 @@ describe('isVisibleSidebarItem', () => {
   it('works with category', () => {
     const subCategoryAllUnlisted = testCategory({
       href: '/sub-category-path',
+      linkUnlisted: true,
       items: [
         {
           type: 'link',
@@ -455,6 +457,7 @@ describe('isVisibleSidebarItem', () => {
         },
         testCategory({
           href: '/sub-sub-category-path',
+          linkUnlisted: true,
           items: [
             {
               type: 'link',
@@ -500,6 +503,22 @@ describe('isVisibleSidebarItem', () => {
     expect(
       isVisibleSidebarItem(categorySomeUnlisted, categorySomeUnlisted.href!),
     ).toBe(true);
+
+    const categoryOnlyIndexListed = testCategory({
+      href: '/category-only-index-listed',
+      items: [
+        {
+          type: 'link',
+          href: '/sub-link-path',
+          label: 'Label',
+          unlisted: true,
+        },
+        subCategoryAllUnlisted,
+      ],
+    });
+    expect(
+      isVisibleSidebarItem(categoryOnlyIndexListed, '/nonexistentPath'),
+    ).toBe(true);
   });
 });
 
@@ -762,3 +781,128 @@ describe('useCurrentSidebarCategory', () => {
     );
   });
 });
+
+describe('useCurrentSidebarSiblings', () => {
+  const createUseCurrentSidebarSiblingsMock =
+    (sidebar?: PropSidebar) => (location: string) =>
+      renderHook(() => useCurrentSidebarSiblings(), {
+        wrapper: ({children}) => (
+          <DocsSidebarProvider name="sidebarName" items={sidebar}>
+            <StaticRouter location={location}>{children}</StaticRouter>
+          </DocsSidebarProvider>
+        ),
+      }).result.current;
+
+  it('works for sidebar category', () => {
+    const category: PropSidebarItemCategory = testCategory({
+      href: '/cat',
+      items: [testLink(), testLink()],
+    });
+    const sidebar: PropSidebar = [
+      testLink(),
+      testLink(),
+      category,
+      testCategory(),
+    ];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarSiblingsMock(sidebar);
+
+    expect(mockUseCurrentSidebarCategory('/cat')).toEqual(category.items);
+  });
+
+  it('works for sidebar root', () => {
+    const category: PropSidebarItemCategory = testCategory({
+      href: '/cat',
+      items: [testLink(), testLink()],
+    });
+    const sidebar: PropSidebar = [
+      testLink({href: '/rootLink'}),
+      testLink(),
+      category,
+      testCategory(),
+    ];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarSiblingsMock(sidebar);
+
+    expect(mockUseCurrentSidebarCategory('/rootLink')).toEqual(sidebar);
+  });
+
+  it('works for nested sidebar category', () => {
+    const category2: PropSidebarItemCategory = testCategory({
+      href: '/cat2',
+      items: [testLink(), testCategory()],
+    });
+    const category1: PropSidebarItemCategory = testCategory({
+      href: '/cat1',
+      items: [testLink(), testLink(), category2, testCategory()],
+    });
+    const sidebar: PropSidebar = [
+      testLink(),
+      testLink(),
+      category1,
+      testCategory(),
+    ];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarSiblingsMock(sidebar);
+
+    expect(mockUseCurrentSidebarCategory('/cat2')).toEqual(category2.items);
+  });
+
+  it('works for category link item', () => {
+    const link = testLink({href: '/my/link/path'});
+    const category: PropSidebarItemCategory = testCategory({
+      href: '/cat1',
+      items: [testLink(), testLink(), link, testCategory()],
+    });
+    const sidebar: PropSidebar = [
+      testLink(),
+      testLink(),
+      category,
+      testCategory(),
+    ];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarSiblingsMock(sidebar);
+
+    expect(mockUseCurrentSidebarCategory('/my/link/path')).toEqual(
+      category.items,
+    );
+  });
+
+  it('works for nested category link item', () => {
+    const link = testLink({href: '/my/link/path'});
+    const category2: PropSidebarItemCategory = testCategory({
+      href: '/cat2',
+      items: [testLink(), testLink(), link, testCategory()],
+    });
+    const category1: PropSidebarItemCategory = testCategory({
+      href: '/cat1',
+      items: [testLink(), testLink(), category2, testCategory()],
+    });
+    const sidebar: PropSidebar = [
+      testLink(),
+      testLink(),
+      category1,
+      testCategory(),
+    ];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarSiblingsMock(sidebar);
+
+    expect(mockUseCurrentSidebarCategory('/my/link/path')).toEqual(
+      category2.items,
+    );
+  });
+
+  it('throws when sidebar is missing', () => {
+    const mockUseCurrentSidebarCategory = createUseCurrentSidebarSiblingsMock();
+    expect(() =>
+      mockUseCurrentSidebarCategory('/cat'),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Unexpected: cant find current sidebar in context"`,
+    );
+  });
+});

packages/docusaurus-plugin-content-docs/src/client/doc.tsx

@@ -50,7 +50,7 @@ export function DocProvider({
 }: {
   children: ReactNode;
   content: PropDocContent;
-}): JSX.Element {
+}): ReactNode {
   const contextValue = useContextValue(content);
   return <Context.Provider value={contextValue}>{children}</Context.Provider>;
 }

packages/docusaurus-plugin-content-docs/src/client/docSidebarItemsExpandedState.tsx

@@ -36,7 +36,7 @@ export function DocSidebarItemsExpandedStateProvider({
   children,
 }: {
   children: ReactNode;
-}): JSX.Element {
+}): ReactNode {
   const [expandedItem, setExpandedItem] = useState<number | null>(null);
   const contextValue = useMemo(
     () => ({expandedItem, setExpandedItem}),

packages/docusaurus-plugin-content-docs/src/client/docsPreferredVersion.tsx

@@ -163,7 +163,7 @@ function DocsPreferredVersionContextProviderUnsafe({
   children,
 }: {
   children: ReactNode;
-}): JSX.Element {
+}): ReactNode {
   const value = useContextValue();
   return <Context.Provider value={value}>{children}</Context.Provider>;
 }
@@ -176,7 +176,7 @@ export function DocsPreferredVersionContextProvider({
   children,
 }: {
   children: ReactNode;
-}): JSX.Element {
+}): ReactNode {
   return (
     <DocsPreferredVersionContextProviderUnsafe>
       {children}

packages/docusaurus-plugin-content-docs/src/client/docsSidebar.tsx

@@ -30,7 +30,7 @@ export function DocsSidebarProvider({
   children: ReactNode;
   name: string | undefined;
   items: PropSidebar | undefined;
-}): JSX.Element {
+}): ReactNode {
   const stableValue: ContextValue | null = useMemo(
     () => (name && items ? {name, items} : null),
     [name, items],

packages/docusaurus-plugin-content-docs/src/client/docsUtils.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useMemo} from 'react';
+import {type ReactNode, useMemo} from 'react';
 import {matchPath, useLocation} from '@docusaurus/router';
 import renderRoutes from '@docusaurus/renderRoutes';
 import {
@@ -132,6 +132,25 @@ export function useCurrentSidebarCategory(): PropSidebarItemCategory {
   return deepestCategory;
 }
 
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarSiblings(): PropSidebarItem[] {
+  const {pathname} = useLocation();
+  const sidebar = useDocsSidebar();
+  if (!sidebar) {
+    throw new Error('Unexpected: cant find current sidebar in context');
+  }
+  const categoryBreadcrumbs = getSidebarBreadcrumbs({
+    sidebarItems: sidebar.items,
+    pathname,
+    onlyCategories: true,
+  });
+  const deepestCategory = categoryBreadcrumbs.slice(-1)[0];
+  return deepestCategory?.items ?? sidebar.items;
+}
+
 const isActive = (testedPath: string | undefined, activePath: string) =>
   typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
 const containsActiveSidebarItem = (
@@ -168,6 +187,7 @@ export function isVisibleSidebarItem(
     case 'category':
       return (
         isActiveSidebarItem(item, activePath) ||
+        (typeof item.href !== 'undefined' && !item.linkUnlisted) ||
         item.items.some((subItem) => isVisibleSidebarItem(subItem, activePath))
       );
     case 'link':
@@ -363,7 +383,7 @@ Available doc ids are:
  */
 export function useDocRootMetadata({route}: DocRootProps): null | {
   /** The element that should be rendered at the current location. */
-  docElement: JSX.Element;
+  docElement: ReactNode;
   /**
    * The name of the sidebar associated with the current doc. `sidebarName` and
    * `sidebarItems` correspond to the value of {@link useDocsSidebar}.

packages/docusaurus-plugin-content-docs/src/client/docsVersion.tsx

@@ -20,7 +20,7 @@ export function DocsVersionProvider({
 }: {
   children: ReactNode;
   version: PropVersionMetadata | null;
-}): JSX.Element {
+}): ReactNode {
   return <Context.Provider value={version}>{children}</Context.Provider>;
 }
 

packages/docusaurus-plugin-content-docs/src/client/index.ts

@@ -33,6 +33,7 @@ export {
   useLayoutDocsSidebar,
   useDocRootMetadata,
   useCurrentSidebarCategory,
+  useCurrentSidebarSiblings,
   filterDocCardListItems,
 } from './docsUtils';
 
@@ -59,6 +60,8 @@ export {
   getDocsVersionSearchTag,
 } from './docsSearch';
 
+export {useBreadcrumbsStructuredData} from './structuredDataUtils';
+
 export type ActivePlugin = {
   pluginId: string;
   pluginData: GlobalPluginData;

packages/docusaurus-plugin-content-docs/src/client/structuredDataUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {PropSidebarBreadcrumbsItem} from '@docusaurus/plugin-content-docs';
+import type {WithContext, BreadcrumbList} from 'schema-dts';
+
+export function useBreadcrumbsStructuredData({
+  breadcrumbs,
+}: {
+  breadcrumbs: PropSidebarBreadcrumbsItem[];
+}): WithContext<BreadcrumbList> {
+  const {siteConfig} = useDocusaurusContext();
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs
+      // We filter breadcrumb items without links, they are not allowed
+      // See also https://github.com/facebook/docusaurus/issues/9319#issuecomment-2643560845
+      .filter((breadcrumb) => breadcrumb.href)
+      .map((breadcrumb, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: breadcrumb.label,
+        item: `${siteConfig.url}${breadcrumb.href}`,
+      })),
+  };
+}

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -6,6 +6,7 @@
  */
 
 import path from 'path';
+import fs from 'fs-extra';
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
 import {
@@ -63,6 +64,37 @@ import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {DocFile, FullVersion} from './types';
 import type {RuleSetRule} from 'webpack';
 
+// MDX loader is not 100% deterministic, leading to cache invalidation issue
+// This permits to invalidate the MDX loader cache entries when content changes
+// Problem documented here: https://github.com/facebook/docusaurus/pull/10934
+// TODO this is not a perfect solution, find better?
+async function createMdxLoaderDependencyFile({
+  dataDir,
+  options,
+  versionsMetadata,
+}: {
+  dataDir: string;
+  options: PluginOptions;
+  versionsMetadata: VersionMetadata[];
+}): Promise<string | undefined> {
+  // TODO this has been temporarily made opt-in until Rspack cache bug is fixed
+  //  See https://github.com/facebook/docusaurus/pull/10931
+  //  See https://github.com/facebook/docusaurus/pull/10934#issuecomment-2672253145
+  if (!process.env.DOCUSAURUS_ENABLE_MDX_DEPENDENCY_FILE) {
+    return undefined;
+  }
+
+  const filePath = path.join(dataDir, '__mdx-loader-dependency.json');
+  // the cache is invalidated whenever this file content changes
+  const fileContent = {
+    options,
+    versionsMetadata,
+  };
+  await fs.ensureDir(dataDir);
+  await fs.writeFile(filePath, JSON.stringify(fileContent));
+  return filePath;
+}
+
 export default async function pluginContentDocs(
   context: LoadContext,
   options: PluginOptions,
@@ -107,6 +139,14 @@ export default async function pluginContentDocs(
     return createMDXLoaderRule({
       include: contentDirs,
       options: {
+        dependencies: [
+          await createMdxLoaderDependencyFile({
+            dataDir,
+            options,
+            versionsMetadata,
+          }),
+        ].filter((d): d is string => typeof d === 'string'),
+
         useCrossCompilerCache:
           siteConfig.future.experimental_faster.mdxCrossCompilerCache,
         admonitions: options.admonitions,

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -20,7 +20,11 @@ declare module '@docusaurus/plugin-content-docs' {
     TagMetadata,
     TagsPluginOptions,
   } from '@docusaurus/utils';
-  import type {Plugin, LoadContext} from '@docusaurus/types';
+  import type {
+    Plugin,
+    LoadContext,
+    OptionValidationContext,
+  } from '@docusaurus/types';
   import type {Overwrite, Required} from 'utility-types';
 
   export type Assets = {
@@ -559,13 +563,18 @@ declare module '@docusaurus/plugin-content-docs' {
     context: LoadContext,
     options: PluginOptions,
   ): Promise<Plugin<LoadedContent>>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
 }
 
 declare module '@theme/DocItem' {
+  import type {ReactNode} from 'react';
   import type {PropDocContent} from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
-    readonly component: () => JSX.Element;
+    readonly component: () => ReactNode;
     readonly exact: boolean;
     readonly path: string;
     readonly sidebar?: string;
@@ -576,10 +585,11 @@ declare module '@theme/DocItem' {
     readonly content: PropDocContent;
   }
 
-  export default function DocItem(props: Props): JSX.Element;
+  export default function DocItem(props: Props): ReactNode;
 }
 
 declare module '@theme/DocCategoryGeneratedIndexPage' {
+  import type {ReactNode} from 'react';
   import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
 
   export interface Props {
@@ -588,39 +598,45 @@ declare module '@theme/DocCategoryGeneratedIndexPage' {
 
   export default function DocCategoryGeneratedIndexPage(
     props: Props,
-  ): JSX.Element;
+  ): ReactNode;
 }
 
 declare module '@theme/DocTagsListPage' {
+  import type {ReactNode} from 'react';
   import type {PropTagsListPage} from '@docusaurus/plugin-content-docs';
 
   export interface Props extends PropTagsListPage {}
-  export default function DocTagsListPage(props: Props): JSX.Element;
+  export default function DocTagsListPage(props: Props): ReactNode;
 }
 
 declare module '@theme/DocTagDocListPage' {
+  import type {ReactNode} from 'react';
   import type {PropTagDocList} from '@docusaurus/plugin-content-docs';
 
   export interface Props {
     readonly tag: PropTagDocList;
   }
-  export default function DocTagDocListPage(props: Props): JSX.Element;
+  export default function DocTagDocListPage(props: Props): ReactNode;
 }
 
 declare module '@theme/DocBreadcrumbs' {
-  export default function DocBreadcrumbs(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DocBreadcrumbs(): ReactNode;
 }
 
 declare module '@theme/DocsRoot' {
+  import type {ReactNode} from 'react';
   import type {RouteConfigComponentProps} from 'react-router-config';
   import type {Required} from 'utility-types';
 
   export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
 
-  export default function DocsRoot(props: Props): JSX.Element;
+  export default function DocsRoot(props: Props): ReactNode;
 }
 
 declare module '@theme/DocVersionRoot' {
+  import type {ReactNode} from 'react';
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
   import type {RouteConfigComponentProps} from 'react-router-config';
   import type {Required} from 'utility-types';
@@ -629,14 +645,15 @@ declare module '@theme/DocVersionRoot' {
     readonly version: PropVersionMetadata;
   }
 
-  export default function DocVersionRoot(props: Props): JSX.Element;
+  export default function DocVersionRoot(props: Props): ReactNode;
 }
 
 declare module '@theme/DocRoot' {
+  import type {ReactNode} from 'react';
   import type {RouteConfigComponentProps} from 'react-router-config';
   import type {Required} from 'utility-types';
 
   export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
 
-  export default function DocRoot(props: Props): JSX.Element;
+  export default function DocRoot(props: Props): ReactNode;
 }

packages/docusaurus-plugin-content-docs/src/versions/files.ts

@@ -75,6 +75,21 @@ export function getDocsDirPathLocalized({
   });
 }
 
+export function getPluginDirPathLocalized({
+  localizationDir,
+  pluginId,
+}: {
+  localizationDir: string;
+  pluginId: string;
+}): string {
+  return getPluginI18nPath({
+    localizationDir,
+    pluginName: 'docusaurus-plugin-content-docs',
+    pluginId,
+    subPaths: [],
+  });
+}
+
 /** `community` => `[siteDir]/community_versions.json` */
 export function getVersionsFilePath(siteDir: string, pluginId: string): string {
   return path.join(siteDir, addPluginIdPrefix(VERSIONS_JSON_FILE, pluginId));

packages/docusaurus-plugin-content-pages/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-pages",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Pages plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-pages.d.ts",
@@ -18,18 +18,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/mdx-loader": "3.6.2",
+    "@docusaurus/mdx-loader": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.2",
+    "@docusaurus/utils-validation": "3.7.0",
     "fs-extra": "^11.1.1",
     "tslib": "^2.6.0",
     "webpack": "^5.88.1"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts

@@ -7,7 +7,11 @@
 
 declare module '@docusaurus/plugin-content-pages' {
   import type {MDXOptions} from '@docusaurus/mdx-loader';
-  import type {LoadContext, Plugin} from '@docusaurus/types';
+  import type {
+    LoadContext,
+    Plugin,
+    OptionValidationContext,
+  } from '@docusaurus/types';
   import type {FrontMatterLastUpdate, LastUpdateData} from '@docusaurus/utils';
 
   export type Assets = {
@@ -82,9 +86,14 @@ declare module '@docusaurus/plugin-content-pages' {
     context: LoadContext,
     options: PluginOptions,
   ): Promise<Plugin<LoadedContent | null>>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
 }
 
 declare module '@theme/MDXPage' {
+  import type {ReactNode} from 'react';
   import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {
     MDXPageMetadata,
@@ -100,5 +109,5 @@ declare module '@theme/MDXPage' {
     >;
   }
 
-  export default function MDXPage(props: Props): JSX.Element;
+  export default function MDXPage(props: Props): ReactNode;
 }

packages/docusaurus-plugin-debug/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-debug",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Debug plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-debug.d.ts",
@@ -20,16 +20,16 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.2",
+    "@docusaurus/core": "3.7.0",
-    "@docusaurus/types": "3.6.2",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.2",
+    "@docusaurus/utils": "3.7.0",
     "fs-extra": "^11.1.1",
-    "react-json-view-lite": "^1.2.0",
+    "react-json-view-lite": "^2.3.0",
     "tslib": "^2.6.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-debug/src/plugin-debug.d.ts

@@ -14,46 +14,57 @@ declare module '@docusaurus/plugin-debug' {
 }
 
 declare module '@theme/DebugConfig' {
-  export default function DebugMetadata(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DebugMetadata(): ReactNode;
 }
 
 declare module '@theme/DebugContent' {
+  import type {ReactNode} from 'react';
   import type {AllContent} from '@docusaurus/types';
 
   export interface Props {
     readonly allContent: AllContent;
   }
-  export default function DebugContent(props: Props): JSX.Element;
+  export default function DebugContent(props: Props): ReactNode;
 }
 
 declare module '@theme/DebugGlobalData' {
-  export default function DebugGlobalData(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DebugGlobalData(): ReactNode;
 }
 
 declare module '@theme/DebugJsonView' {
+  import type {ReactNode} from 'react';
+
   export interface Props {
     readonly src: unknown;
     readonly collapseDepth?: number;
   }
-  export default function DebugJsonView(props: Props): JSX.Element;
+  export default function DebugJsonView(props: Props): ReactNode;
 }
 
 declare module '@theme/DebugLayout' {
   import type {ReactNode} from 'react';
 
-  export default function DebugLayout(props: {
+  export default function DebugLayout(props: {children: ReactNode}): ReactNode;
-    children: ReactNode;
-  }): JSX.Element;
 }
 
 declare module '@theme/DebugRegistry' {
-  export default function DebugRegistry(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DebugRegistry(): ReactNode;
 }
 
 declare module '@theme/DebugRoutes' {
-  export default function DebugRoutes(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DebugRoutes(): ReactNode;
 }
 
 declare module '@theme/DebugSiteMetadata' {
-  export default function DebugSiteMetadata(): JSX.Element;
+  import type {ReactNode} from 'react';
+
+  export default function DebugSiteMetadata(): ReactNode;
 }

packages/docusaurus-plugin-debug/src/theme/DebugConfig/index.tsx

@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ReactNode} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import DebugLayout from '@theme/DebugLayout';
 import DebugJsonView from '@theme/DebugJsonView';
 
-export default function DebugMetadata(): JSX.Element {
+export default function DebugMetadata(): ReactNode {
   const {siteConfig} = useDocusaurusContext();
   return (
     <DebugLayout>

packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ReactNode} from 'react';
 
 import DebugLayout from '@theme/DebugLayout';
 import DebugJsonView from '@theme/DebugJsonView';
@@ -52,7 +52,7 @@ function PluginContent({
   );
 }
 
-export default function DebugContent({allContent}: Props): JSX.Element {
+export default function DebugContent({allContent}: Props): ReactNode {
   return (
     <DebugLayout>
       <h2>Plugin content</h2>

packages/docusaurus-plugin-debug/src/theme/DebugGlobalData/index.tsx

@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ReactNode} from 'react';
 import useGlobalData from '@docusaurus/useGlobalData';
 import DebugLayout from '@theme/DebugLayout';
 import DebugJsonView from '@theme/DebugJsonView';
 
-export default function DebugMetadata(): JSX.Element {
+export default function DebugMetadata(): ReactNode {
   const globalData = useGlobalData();
   return (
     <DebugLayout>

packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ReactNode} from 'react';
 import {
   JsonView,
   defaultStyles,
@@ -30,12 +30,10 @@ const paraisoStyles: JsonViewProps['style'] = {
   collapseIcon: styles.collapseIconParaiso!,
   expandIcon: styles.expandIconParaiso!,
   collapsedContent: styles.collapseContentParaiso!,
+  childFieldsContainer: styles.childFieldsContainerParaiso!,
 };
 
-export default function DebugJsonView({
+export default function DebugJsonView({src, collapseDepth}: Props): ReactNode {
-  src,
-  collapseDepth,
-}: Props): JSX.Element {
   return (
     <JsonView
       data={src as object}

packages/docusaurus-plugin-debug/src/theme/DebugJsonView/styles.module.css

@@ -99,3 +99,12 @@
 .collapseContentParaiso::after {
   content: '...';
 }
+
+/*
+Overrides default ul style from Infima
+See https://github.com/AnyRoad/react-json-view-lite/issues/38
+*/
+.childFieldsContainerParaiso {
+  margin: 0;
+  padding: 0;
+}

packages/docusaurus-plugin-debug/src/theme/DebugLayout/index.tsx

@@ -29,7 +29,7 @@ export default function DebugLayout({
   children,
 }: {
   children: ReactNode;
-}): JSX.Element {
+}): ReactNode {
   return (
     <>
       <Head>