chore(website): upgrade to DocSearch 4.4.0 + fix little website theming issues (#11626)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: sebastien <lorber.sebastien@gmail.com>

.cspell.json

@@ -21,11 +21,15 @@
   ],
   "ignorePaths": [
     "CHANGELOG.md",
+    "CHANGELOG-v*.md",
+    "patches",
     "packages/docusaurus-theme-translations/locales",
+    "packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy",
     "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",
-  "settings": {
-    "[typescript]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
-    },
-    "[json]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
-    },
-    "[jsonc]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "[typescript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        },
+        "[json]": {
+          "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"
   }

.eslintignore

@@ -22,3 +22,6 @@ packages/create-docusaurus/templates/facebook
 
 website/_dogfooding/_swizzle_theme_tests
 website/_dogfooding/_asset-tests/badSyntax.js
+
+
+packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy

.eslintrc.js

@@ -60,6 +60,7 @@ module.exports = {
   },
   reportUnusedDisableDirectives: true,
   plugins: [
+    'react-compiler',
     'react-hooks',
     'header',
     'jest',
@@ -68,6 +69,7 @@ module.exports = {
     '@docusaurus',
   ],
   rules: {
+    'react-compiler/react-compiler': ERROR,
     'react/jsx-uses-react': OFF, // JSX runtime: automatic
     'react/react-in-jsx-scope': OFF, // JSX runtime: automatic
     'array-callback-return': WARNING,
@@ -212,7 +214,7 @@ module.exports = {
     ],
     'no-useless-escape': WARNING,
     'no-void': [ERROR, {allowAsStatement: true}],
-    'prefer-destructuring': WARNING,
+    'prefer-destructuring': OFF,
     'prefer-named-capture-group': WARNING,
     'prefer-template': WARNING,
     yoda: WARNING,
@@ -296,13 +298,13 @@ module.exports = {
     'jest/expect-expect': OFF,
     'jest/no-large-snapshots': [
       WARNING,
-      {maxSize: Infinity, inlineMaxSize: 10},
+      {maxSize: Infinity, inlineMaxSize: 50},
     ],
     'jest/no-test-return-statement': ERROR,
     'jest/prefer-expect-resolves': WARNING,
     'jest/prefer-lowercase-title': [WARNING, {ignore: ['describe']}],
     'jest/prefer-spy-on': WARNING,
-    'jest/prefer-to-be': WARNING,
+    'jest/prefer-to-be': OFF,
     'jest/prefer-to-have-length': WARNING,
     'jest/require-top-level-describe': ERROR,
     'jest/valid-title': [
@@ -380,7 +382,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

@@ -27,12 +27,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Use Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
+          cache: yarn
 
       - name: Install dependencies
         run: yarn || yarn || yarn

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

@@ -22,9 +22,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -32,3 +32,5 @@ jobs:
         run: yarn || yarn || yarn
       - name: Build blog-only
         run: yarn workspace website build:blogOnly
+        env:
+          DOCUSAURUS_PERF_LOGGER: 'true'

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

@@ -25,9 +25,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -37,26 +37,27 @@ jobs:
       - name: Build Hash Router
         run: yarn build:website:fast
         env:
+          DOCUSAURUS_PERF_LOGGER: 'true'
           DOCUSAURUS_ROUTER: 'hash'
           # Note: hash router + baseUrl do not play well together
           # This would host at https://facebook.github.io/docusaurus/#/docusaurus/
           # BASE_URL: '/docusaurus/' # hash router +
 
       - name: Upload Website artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: website-hash-router-archive
           path: website/build
 
       #- name: Upload Website Pages artifact
-      #  uses: actions/upload-pages-artifact@v3
+      #  uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
       #  with:
       #    path: website/build
 
       # Deploy to https://facebook.github.io/docusaurus/
       - name: Deploy to GitHub Pages
         if: ${{ github.event_name != 'pull_request' && github.ref_name == 'main' }}
-        uses: peaceiris/actions-gh-pages@v4
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: website/build
@@ -80,4 +81,4 @@ jobs:
   #  steps:
   #     - name: Deploy to GitHub Pages
   #      id: deployment
-  #      uses: actions/deploy-pages@v4
+  #      uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/build-perf.yml

@@ -41,14 +41,14 @@ jobs:
         DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Track build size changes
-        uses: preactjs/compressed-size-action@6fa0e7ca017120c754863b31123c5ee2860fd434 # v2
+        uses: preactjs/compressed-size-action@8518045ed95e94e971b83333085e1cb99aa18aa8 # v2.9.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           build-script: build:website:fast
@@ -62,6 +62,7 @@ jobs:
           comment-key: DOCUSAURUS_INFRA_${{ matrix.DOCUSAURUS_INFRA }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
   # Ensures build times stay under reasonable thresholds
   build-time:
@@ -73,9 +74,9 @@ jobs:
         DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -85,15 +86,18 @@ jobs:
       # Ensure build with a cold cache does not increase too much
       - name: Build (cold cache)
         run: yarn build:website:fast
-        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 3 || 1  }}
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 3 || 2  }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
       # Ensure build with a warm cache does not increase too much
       - name: Build (warm cache)
         run: yarn build:website:fast
-        timeout-minutes: 1
+        # Temporary: upper value for Rspack until incremental cache works better
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 1 || 2  }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
     # TODO post a GitHub comment with build with perf warnings?

.github/workflows/canary-release.yml

@@ -20,11 +20,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         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@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/codeql-analysis.yml

@@ -33,12 +33,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@2c779ab0d087cd7fe7b826087247c2c81f27bfa6 # 3.26.5
+        uses: github/codeql-action/init@4e94bd11f71e507f7f87df81788dff88d1dacbfb # 4.31.0
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@2c779ab0d087cd7fe7b826087247c2c81f27bfa6 # 3.26.5
+        uses: github/codeql-action/analyze@4e94bd11f71e507f7f87df81788dff88d1dacbfb # 4.31.0

.github/workflows/continuous-releases.yml

@@ -18,10 +18,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/dependency-review.yml

@@ -13,6 +13,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Dependency Review
-        uses: actions/dependency-review-action@4081bf99e2866ebe428fc0477b69eb4fcda7220a # 4.4.0
+        uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # 4.8.2

.github/workflows/lighthouse-report.yml

@@ -1,7 +1,7 @@
 name: Lighthouse Report
 
 on:
-  pull_request_target:
+  pull_request:
     branches:
       - main
       - docusaurus-v**
@@ -21,12 +21,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Use Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
+          cache: yarn
 
       - name: Install dependencies
         run: yarn || yarn || yarn
@@ -36,7 +37,7 @@ jobs:
 
       - name: Audit URLs using Lighthouse
         id: lighthouse_audit
-        uses: treosh/lighthouse-ci-action@2f8dda6cf4de7d73b29853c3f29e73a01e297bd8 # 12.1.0
+        uses: treosh/lighthouse-ci-action@fcd65974f7c4c2bf0ee9d09b84d2489183c29726 # 12.6.1
         with:
           urls: |
             http://localhost:3000
@@ -52,7 +53,7 @@ jobs:
 
       - name: Format lighthouse score
         id: format_lighthouse_score
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # 7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # 8.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -64,7 +65,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@773744901bac0e8cbb5a0dc842800d45e9b2b405 # 2.9.4
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lint-autofix.yml

@@ -19,7 +19,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           repository: ${{ github.event.pull_request.head.repo.full_name }}
           ref: ${{ github.head_ref }}
@@ -42,6 +42,6 @@ jobs:
       - name: Print Diff
         run: git diff
 
-      - uses: stefanzweifel/git-auto-commit-action@v5
+      - uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
         with:
           commit_message: 'refactor: apply lint autofix'

.github/workflows/lint.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.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

@@ -22,9 +22,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-e2e.yml

@@ -38,12 +38,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -68,10 +68,52 @@ 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
 
+  yarn-v1-windows:
+    name: E2E — Yarn v1 Windows
+    timeout-minutes: 30
+    runs-on: windows-8-core
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Use Node.js LTS
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: Installation
+        run: yarn || yarn || yarn
+      - name: Generate test-website project against main branch
+        # Not using test-release.sh => no verdaccio docker image on Windows
+        # run: bash ./admin/scripts/test-release.sh -s
+        run: yarn create-docusaurus test-website-in-workspace classic --typescript
+      - name: Install test-website project with Yarn v1
+        run: yarn || yarn || yarn
+        working-directory: test-website-in-workspace
+      - name: Start test-website project
+        run: yarn start --no-open
+        working-directory: test-website-in-workspace
+        env:
+          E2E_TEST: true
+      - name: Build test-website project
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+        working-directory: test-website-in-workspace
+      - name: Upload Website artifact
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: website-e2e-windows
+          path: test-website-in-workspace/build
+
   yarn-berry:
     name: E2E — Yarn Berry
     timeout-minutes: 30
@@ -82,9 +124,9 @@ jobs:
         variant: [-s, -st]
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -151,9 +193,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -181,7 +223,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
 
@@ -191,9 +233,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -223,6 +265,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

@@ -26,9 +26,9 @@ jobs:
         variant: ['js', 'ts']
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node LTS
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-windows.yml

@@ -27,16 +27,17 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Support longpaths
         run: git config --system core.longpaths true
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
+          cache: yarn
       - name: Installation
         run: yarn || yarn || yarn
       - name: Docusaurus Jest Tests
@@ -53,14 +54,20 @@ jobs:
         run: yarn workspace website test:swizzle:wrap:ts
       - name: Docusaurus Build
         run: yarn build:website:fast
+        env:
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
       - name: TypeCheck website
-        # TODO temporary, remove TS skipLibCheck
         # see https://github.com/facebook/docusaurus/pull/10486
-        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json
+        run: yarn workspace website typecheck
       - name: TypeCheck website - min version - v5.1
         run: |
           yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
+
+          # DocSearch@4/ai@5 doesn't support TS 5.1 (with skipLibCheck=false)
+          jq '.resolutions."@docsearch/react" = "^3.9.0"' package.json > package.json.tmp && mv -Force package.json.tmp package.json
+          yarn add @docsearch/react@^3.9.0 --exact -D -W --ignore-scripts
+
           yarn workspace website typecheck
       - name: TypeCheck website - max version - Latest
         # For latest TS there are often lib check errors, so we disable it

.github/workflows/tests.yml

@@ -27,12 +27,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -49,18 +49,22 @@ 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
 
       - name: TypeCheck website
-        # TODO temporary, remove TS skipLibCheck
         # see https://github.com/facebook/docusaurus/pull/10486
-        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json
+        run: yarn workspace website typecheck
       - name: TypeCheck website - min version - v5.1
         run: |
           yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
+
+          # DocSearch@4/ai@5 doesn't support TS 5.1 (with skipLibCheck=false)
+          jq '.resolutions."@docsearch/react" = "^3.9.0"' package.json > package.json.tmp && mv -f package.json.tmp package.json
+          yarn add @docsearch/react@^3.9.0 --exact -D -W --ignore-scripts
+
           yarn workspace website typecheck
       - name: TypeCheck website - max version - Latest
         # For latest TS there are often lib check errors, so we disable it

.gitignore

@@ -45,3 +45,10 @@ website/i18n/**/*
 #!website/i18n/fr/**/*
 
 .netlify
+
+website/rspack-tracing.json
+website/rspack-tracing.pftrace
+website/bundler-cpu-profile.json
+website/profile.json.gz
+
+

.nvmrc

@@ -1 +1 @@
-18
+22

.prettierignore

@@ -1,15 +1,18 @@
 dist
 node_modules
 .yarn
-build
+**/build/**
 coverage
 .docusaurus
+.idea
 
 .svg
 *.svg
 
 jest/vendor
 
+argos/test-results
+
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*

CONTRIBUTING.md

@@ -82,7 +82,7 @@ Apart from the `good first issue`, the following labels are also worth looking a
 - [`help wanted`](https://github.com/facebook/docusaurus/labels/help%20wanted): if you have specific knowledge in one domain, working on these issues can make your expertise shine.
 - [`status: accepting pr`](https://github.com/facebook/docusaurus/labels/status%3A%20accepting%20pr): community contributors can feel free to claim any of these.
 
-If you want to work on any of these issues, just drop a message saying "I'd like to work on this", and we will assign the issue to you and update the issue's status as "claimed". **You are expected to send a pull request within seven days** after that, so we can still delegate the issue to someone else if you are unavailable.
+If you want to work on any of these issues, just drop a message saying "I am working on this". **You do not need to ask for assignment to work on any issue explicitly marked as welcoming external contributions.** However, don't "cookie lick", or squat on an issue without actually sending a PR. You are automatically considered as giving up if you don't **send a PR within seven days after your comment**, and the issue automatically becomes up for grabs again.
 
 Alternatively, when opening an issue, you can also click the "self service" checkbox to indicate that you'd like to work on the issue yourself, which will also make us see the issue as "claimed".
 
@@ -214,6 +214,16 @@ After you have signed the CLA, the CLA bot would automatically update the PR sta
 
 If it happens that you were unavailable and your PR gets closed, feel free to reopen once it's ready! We are still happy to review it, help you complete it, and eventually merge it.
 
+### AI-assisted PRs
+
+We welcome the use of AI tools for authoring PRs, and we love to see people pushing the boundaries of AI capabilities. The core team actively uses different AI tools in our development process. However, we are aware that **many people are sending entirely AI-generated PRs as a low-effort way to farm OSS contributions**, so please be mindful of the following etiquette to show your respect for our time and our codebase:
+
+- **Be transparent**: If a significant portion of your code is AI generated, please indicate that in your PR description.
+- **Be accountable**: You are responsible for the code you submit, regardless of whether it was generated by AI or written by you. You should be able to explain every line of the code, ensure all tests pass, and address our reviews.
+- **Be reasonable**: Sometimes we receive 1k LOC PRs that are obviously AI-generated and implement unsolicited features. Please note that significant changes require prior communication and approval from the team in the form of an issue.
+
+We retain the right to close any PR that we deem as unproductive or low-effort, even when we agree with the spirit of the change.
+
 ### Breaking Changes
 
 When adding a new breaking change, follow this template in your pull request:
@@ -227,6 +237,10 @@ When adding a new breaking change, follow this template in your pull request:
 - **Severity (number of people affected x effort)**:
 ```
 
+> [!NOTE]
+>
+> Breaking changes should be discussed in the issue tracker before being implemented.
+
 ### What Happens Next?
 
 The core Docusaurus team will be monitoring pull requests. Do help us by keeping pull requests consistent by following the guidelines above.

README.md

@@ -45,7 +45,7 @@ Short on time? Check out our [5-minute tutorial ⏱️](https://tutorial.docusau
 
 - **Customizable**
 
-> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
+> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
 
 ## Installation
 
@@ -120,4 +120,4 @@ The Docusaurus documentation (e.g., `.md` files in the `/docs` folder) is [Creat
 
 [![Rocket Validator logo](./admin/img/rocketvalidator-logo.png)](https://rocketvalidator.com/)
 
-[Rocket Validator](https://rocketvalidator.com/) helps us find HTML markup or accessibility issues.
+[Rocket Validator](https://rocketvalidator.com/) helps us find [HTML markup and accessibility issues](https://rocketvalidator.com/stats/docusaurus.io).

admin/new.docusaurus.io/package.json

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

admin/publish.md

@@ -78,7 +78,7 @@ Not all labels will appear in the changelog—some are designed not to. However,
 is:pr is:merged sort:updated-desc -label:"pr: breaking change","pr: new feature","pr: bug fix","pr: performance","pr: polish","pr: documentation","pr: maintenance","pr: internal","pr: dependencies","pr: showcase"
 ```
 
-[Check tags of all recently merged Pull-Requests](https://github.com/facebook/docusaurus/pulls?q=is%3Apr+is%3Amerged+sort%3Aupdated-desc+-label%3A%22pr%3A+breaking+change%22%2C%22pr%3A+new+feature%22%2C%22pr%3A+bug+fix%22%2C%22pr%3A+performance%22%2C%22pr%3A+polish%22%2C%22pr%3A+documentation%22%2C%22pr%3A+maintenance%22%2C%22pr%3A+internal%22%2C%22pr%3A+dependencies%22%2C%22pr%3A+showcase%22)
+[Check tags of all recently merged Pull-Requests](https://github.com/facebook/docusaurus/pulls?q=is%3Apr+is%3Amerged+sort%3Aupdated-desc+-label%3A%22pr%3A+breaking+change%22%2C%22pr%3A+new+feature%22%2C%22pr%3A+bug+fix%22%2C%22pr%3A+performance%22%2C%22pr%3A+polish%22%2C%22pr%3A+documentation%22%2C%22pr%3A+maintenance%22%2C%22pr%3A+internal%22%2C%22pr%3A+dependencies%22%2C%22pr%3A+showcase%22%2C%22pr%3A+ignore%22%2C%22pr%3A+translations%22+)
 
 Some general principles about the labeling process:
 

admin/scripts/resizeImage.js

@@ -9,9 +9,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import {fileURLToPath} from 'url';
 import {program} from 'commander';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import sharp from 'sharp';
-import imageSize from 'image-size';
+import {imageSizeFromFile} from 'image-size/fromFile';
 
 // You can use it as:
 //
@@ -64,7 +64,7 @@ program
 
     await Promise.all(
       images.map(async (imgPath) => {
-        const {width, height} = imageSize(imgPath);
+        const {width, height} = await imageSizeFromFile(imgPath);
         const targetWidth =
           options.width ?? (imgPath.includes(showcasePath) ? 640 : 1000);
         const targetHeight =

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"
@@ -51,8 +53,11 @@ git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 # The website is generated outside the repo to minimize chances of yarn resolving the wrong version
 cd ..
 
+echo Generating test-website in `pwd`
+
 # 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.1",
+  "version": "3.9.2",
   "private": true,
   "dependencies": {
     "@mdx-js/react": "1.0.1",

argos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argos",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "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,13 @@ 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
-    // on /blog/releases/2.4
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-theme=light"',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?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"',
-    // on /docs/styling-layout
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-data-navbar=false&docusaurus-data-red-border"',
-    '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"',
+    // Warning because react-live not supporting React automatic JSX runtime
+    // See https://github.com/FormidableLabs/react-live/issues/405
+    'Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance',
 
     // TODO weird problem related to KaTeX fonts refusing to decode?
     //  on /docs/markdown-features/math-equations

crowdin-v2.yaml

@@ -20,6 +20,19 @@ languages_mapping: &languages_mapping
   two_letters_code:
     pt-BR: pt-BR
 
+# Crowdin regularly update their MDX parser
+# Unfortunately, their v2 parser is more "MDX compliant" and thus can't parse
+# Docusaurus MDX files correctly due to our custom {#headingId} syntax.
+# Adding this type param permits using their older v1.2 parser.
+# Note: you can find the version of a file using browser DevTools
+# The source file icons will have a class such as "file_type_mdx_v1_2"
+#
+# TODO fix our headingId syntax
+# providing an explicit type is annoying and not future-proof
+# there's a risk that when adding an image in /docs, it will be parsed as mdx
+# and duplicating source file configs for various extensions is not great either
+mdx_file_type: &mdx_file_type mdx_v1_2
+
 #
 # Files configuration
 #
@@ -27,18 +40,33 @@ files:
   - source: /website/i18n/en/**/*
     translation: /website/i18n/%two_letters_code%/**/%original_file_name%
     languages_mapping: *languages_mapping
+
+  - source: /website/docs/**/*.mdx
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+    type: *mdx_file_type
   - source: /website/docs/**/*
     translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
     languages_mapping: *languages_mapping
-  - source: /website/community/**/*
-    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
+    ignore: [/**/*.mdx]
+
+  - source: /website/versioned_docs/**/*.mdx
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
     languages_mapping: *languages_mapping
+    type: *mdx_file_type
   - source: /website/versioned_docs/**/*
     translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
     languages_mapping: *languages_mapping
+    ignore: [/**/*.mdx]
+
+  - source: /website/community/**/*
+    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
+    languages_mapping: *languages_mapping
+
   - source: /website/blog/**/*
     translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
     languages_mapping: *languages_mapping
+
   - source: /website/src/pages/**/*
     translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
     ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css]

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

@@ -2,40 +2,40 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+## Installation
 
-```
-$ yarn
+```bash
+yarn
 ```
 
-### Local Development
+## Local Development
 
-```
-$ yarn start
+```bash
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+## Build
 
-```
-$ yarn build
+```bash
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
 Using SSH:
 
-```
-$ USE_SSH=true yarn deploy
+```bash
+USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/classic-typescript/blog/authors.yml

@@ -1,12 +1,14 @@
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  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

examples/classic-typescript/docs/intro.md

@@ -14,7 +14,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 ### What you'll need
 
-- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
+- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
   - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
 
 ## Generate a new site

examples/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
@@ -21,7 +26,6 @@ const config: Config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -67,6 +71,9 @@ const config: Config = {
   themeConfig: {
     // Replace with your project's social card
     image: 'img/docusaurus-social-card.jpg',
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
     navbar: {
       title: 'My Site',
       logo: {

examples/classic-typescript/package.json

@@ -16,18 +16,18 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.0",
-    "@docusaurus/preset-classic": "3.6.0",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.0",
-    "@docusaurus/tsconfig": "3.6.0",
-    "@docusaurus/types": "3.6.0",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/tsconfig": "3.9.2",
+    "@docusaurus/types": "3.9.2",
     "typescript": "~5.6.2"
   },
   "browserslist": {
@@ -43,7 +43,7 @@
     ]
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
   "description": "Docusaurus example project (classic-typescript template)"
 }

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

@@ -2,40 +2,40 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+## Installation
 
-```
-$ yarn
+```bash
+yarn
 ```
 
-### Local Development
+## Local Development
 
-```
-$ yarn start
+```bash
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+## Build
 
-```
-$ yarn build
+```bash
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
 Using SSH:
 
-```
-$ USE_SSH=true yarn deploy
+```bash
+USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

examples/classic/blog/authors.yml

@@ -1,12 +1,14 @@
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  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

examples/classic/docs/intro.md

@@ -14,7 +14,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 ### What you'll need
 
-- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
+- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
   - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
 
 ## Generate a new site

examples/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
@@ -26,7 +31,6 @@ const config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -75,6 +79,9 @@ const config = {
     ({
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
+      colorMode: {
+        respectPrefersColorScheme: true,
+      },
       navbar: {
         title: 'My Site',
         logo: {

examples/classic/package.json

@@ -15,17 +15,17 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.0",
-    "@docusaurus/preset-classic": "3.6.0",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.0",
-    "@docusaurus/types": "3.6.0"
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/types": "3.9.2"
   },
   "browserslist": {
     "production": [
@@ -40,7 +40,7 @@
     ]
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
   "description": "Docusaurus example project"
 }

jest.config.mjs

@@ -32,15 +32,16 @@ const ignorePatterns = [
 export default {
   rootDir: fileURLToPath(new URL('.', import.meta.url)),
   verbose: true,
+  // Default 5s timeout often fails on Windows :s,
+  // see https://github.com/facebook/docusaurus/pull/8259
+  testTimeout: 15000,
   setupFiles: ['./jest/setup.js'],
   testEnvironmentOptions: {
     url: 'https://docusaurus.io/',
   },
   testEnvironment: 'node',
   testPathIgnorePatterns: ignorePatterns,
-  // Default 5s timeout often fails on Windows :s,
-  // see https://github.com/facebook/docusaurus/pull/8259
-  testTimeout: 15000,
+  watchPathIgnorePatterns: ['/\\.docusaurus'],
   coveragePathIgnorePatterns: [
     ...ignorePatterns,
     // We also ignore all package entry points

jest/deps.d.ts

@@ -12,8 +12,3 @@ declare module 'to-vfile' {
 
   export function read(path: string, encoding?: string): Promise<VFile>;
 }
-
-declare module '@testing-utils/git' {
-  const createTempRepo: typeof import('./utils/git').createTempRepo;
-  export {createTempRepo};
-}

jest/snapshotPathNormalizer.ts

@@ -82,7 +82,7 @@ function normalizePaths<T>(value: T): T {
     (val) => val.split(cwdReal).join('<PROJECT_ROOT>'),
     (val) => val.split(cwd).join('<PROJECT_ROOT>'),
 
-    // Replace home directory with <TEMP_DIR>
+    // Replace temp directory with <TEMP_DIR>
     (val) => val.split(tempDirReal).join('<TEMP_DIR>'),
     (val) => val.split(tempDir).join('<TEMP_DIR>'),
 

jest/utils/git.ts

@@ -1,63 +0,0 @@
-/**
- * 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 fs from 'fs-extra';
-import os from 'os';
-import path from 'path';
-import shell from 'shelljs';
-
-class Git {
-  constructor(private dir: string) {
-    const res = shell.exec('git init', {cwd: dir, silent: true});
-    if (res.code !== 0) {
-      throw new Error(`git init exited with code ${res.code}.
-stderr: ${res.stderr}
-stdout: ${res.stdout}`);
-    }
-    // Doesn't matter currently
-    shell.exec('git config user.email "test@jc-verse.com"', {
-      cwd: dir,
-      silent: true,
-    });
-    shell.exec('git config user.name "Test"', {cwd: dir, silent: true});
-
-    shell.exec('git commit --allow-empty -m "First commit"', {
-      cwd: dir,
-      silent: true,
-    });
-  }
-  commit(msg: string, date: string, author: string): void {
-    const addRes = shell.exec('git add .', {cwd: this.dir, silent: true});
-    const commitRes = shell.exec(
-      `git commit -m "${msg}" --date "${date}T00:00:00Z" --author "${author}"`,
-      {
-        cwd: this.dir,
-        env: {GIT_COMMITTER_DATE: `${date}T00:00:00Z`},
-        silent: true,
-      },
-    );
-    if (addRes.code !== 0) {
-      throw new Error(`git add exited with code ${addRes.code}.
-stderr: ${addRes.stderr}
-stdout: ${addRes.stdout}`);
-    }
-    if (commitRes.code !== 0) {
-      throw new Error(`git commit exited with code ${commitRes.code}.
-stderr: ${commitRes.stderr}
-stdout: ${commitRes.stdout}`);
-    }
-  }
-}
-
-// This function is sync so the same mock repo can be shared across tests
-export function createTempRepo(): {repoDir: string; git: Git} {
-  const repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'git-test-repo'));
-
-  const git = new Git(repoDir);
-
-  return {repoDir, git};
-}

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.1",
+  "version": "3.9.2",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "useNx": false,
@@ -13,7 +13,8 @@
       "pr: polish": ":nail_care: Polish",
       "pr: documentation": ":memo: Documentation",
       "pr: dependencies": ":robot: Dependencies",
-      "pr: maintenance": ":wrench: Maintenance"
+      "pr: maintenance": ":wrench: Maintenance",
+      "pr: translations": ":globe_with_meridians: Translations"
     },
     "cacheDir": ".changelog"
   }

package.json

@@ -15,6 +15,7 @@
   "scripts": {
     "start": "yarn build:packages && yarn start:website",
     "start:website": "yarn workspace website start",
+    "start:website:profile": "DOCUSAURUS_BUNDLER_CPU_PROFILE=true DOCUSAURUS_RSPACK_TRACE=true yarn workspace website start",
     "start:website:baseUrl": "yarn workspace website start:baseUrl",
     "start:website:blogOnly": "yarn workspace website start:blogOnly",
     "start:website:deployPreview": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website start",
@@ -22,6 +23,7 @@
     "build": "yarn build:packages && yarn build:website",
     "build:packages": "lerna run build --no-private",
     "build:website": "yarn workspace website build",
+    "build:website:profile": "DOCUSAURUS_BUNDLER_CPU_PROFILE=true DOCUSAURUS_RSPACK_TRACE=true yarn workspace website build",
     "build:website:baseUrl": "yarn workspace website build:baseUrl",
     "build:website:blogOnly": "yarn workspace website build:blogOnly",
     "build:website:deployPreview:testWrap": "yarn workspace website test:swizzle:wrap:ts",
@@ -29,8 +31,9 @@
     "build:website:deployPreview": "yarn build:website:deployPreview:testWrap && yarn build:website:deployPreview:build",
     "build:website:fast": "yarn workspace website build:fast",
     "build:website:fast:rsdoctor": "yarn workspace website build:fast:rsdoctor",
-    "build:website:fast:profile": "yarn workspace website build:fast:profile",
     "build:website:en": "yarn workspace website build --locale en",
+    "profile:bundle:cpu": "yarn workspace website profile:bundle:cpu:profile",
+    "profile:bundle:samply": "yarn workspace website profile:bundle:samply",
     "clear:website": "yarn workspace website clear",
     "serve:website": "yarn workspace website serve",
     "serve:website:baseUrl": "serve website",
@@ -50,7 +53,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 .",
@@ -59,7 +62,7 @@
     "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
     "lint:js:fix": "yarn lint:js --fix",
     "lint:spelling": "cspell \"**\" --no-progress --show-context --show-suggestions",
-    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=en_US.UTF-8 sort --ignore-case >> project-words.txt",
+    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=C sort --ignore-case >> project-words.txt",
     "lint:style": "stylelint \"**/*.css\"",
     "lint:style:fix": "yarn lint:style --fix",
     "lerna": "lerna",
@@ -83,14 +86,13 @@
     "@types/node": "^18.16.19",
     "@types/prompts": "^2.4.4",
     "@types/react": "^18.2.15",
-    "@types/react-dev-utils": "^9.0.11",
     "@types/react-test-renderer": "^18.0.0",
     "@types/semver": "^7.5.0",
     "@types/shelljs": "^0.8.12",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
-    "cspell": "^8.1.0",
+    "cspell": "^8.18.1",
     "eslint": "^8.45.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^8.8.0",
@@ -99,10 +101,11 @@
     "eslint-plugin-jest": "^27.2.3",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-compiler": "^19.0.0-beta-40c6c23-20250301",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-regexp": "^1.15.0",
     "husky": "^8.0.3",
-    "image-size": "^1.0.2",
+    "image-size": "^2.0.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-serializer-ansi-escapes": "^3.0.0",
@@ -112,10 +115,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 +127,7 @@
     "stylelint": "^14.16.1",
     "stylelint-config-prettier": "^9.0.5",
     "stylelint-config-standard": "^29.0.0",
-    "typescript": "~5.6.2"
-  }
+    "typescript": "~5.8.2"
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,14 +22,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.1",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "commander": "^5.1.0",
+    "execa": "^5.1.1",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "prompts": "^2.4.2",
     "semver": "^7.5.4",
-    "shelljs": "^0.8.5",
     "supports-color": "^9.4.0",
     "tslib": "^2.6.0"
   },
@@ -37,6 +37,6 @@
     "@types/supports-color": "^8.1.1"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   }
 }

packages/create-docusaurus/src/index.ts

@@ -10,10 +10,13 @@ import {fileURLToPath} from 'url';
 import path from 'path';
 import _ from 'lodash';
 import {logger} from '@docusaurus/logger';
-import shell from 'shelljs';
+import execa from 'execa';
 import prompts, {type Choice} from 'prompts';
 import supportsColor from 'supports-color';
-import {escapeShellArg, askPreferredLanguage} from '@docusaurus/utils';
+
+// TODO remove dependency on large @docusaurus/utils
+//  would be better to have a new smaller @docusaurus/utils-cli package
+import {askPreferredLanguage} from '@docusaurus/utils';
 
 type LanguagesOptions = {
   javascript?: boolean;
@@ -70,9 +73,9 @@ function findPackageManagerFromUserAgent(): PackageManager | undefined {
 }
 
 async function askForPackageManagerChoice(): Promise<PackageManager> {
-  const hasYarn = shell.exec('yarn --version', {silent: true}).code === 0;
-  const hasPnpm = shell.exec('pnpm --version', {silent: true}).code === 0;
-  const hasBun = shell.exec('bun --version', {silent: true}).code === 0;
+  const hasYarn = (await execa.command('yarn --version')).exitCode === 0;
+  const hasPnpm = (await execa.command('pnpm --version')).exitCode === 0;
+  const hasBun = (await execa.command('bun --version')).exitCode === 0;
 
   if (!hasYarn && !hasPnpm && !hasBun) {
     return 'npm';
@@ -270,7 +273,10 @@ async function getSiteName(
       return 'A website name is required.';
     }
     const dest = path.resolve(rootDir, siteName);
-    if (await fs.pathExists(dest)) {
+    if (siteName === '.' && (await fs.readdir(dest)).length > 0) {
+      return logger.interpolate`Directory not empty at path=${dest}!`;
+    }
+    if (siteName !== '.' && (await fs.pathExists(dest))) {
       return logger.interpolate`Directory already exists at path=${dest}!`;
     }
     return true;
@@ -530,10 +536,7 @@ export default async function init(
 
   if (source.type === 'git') {
     const gitCommand = await getGitCommand(source.strategy);
-    const gitCloneCommand = `${gitCommand} ${escapeShellArg(
-      source.url,
-    )} ${escapeShellArg(dest)}`;
-    if (shell.exec(gitCloneCommand).code !== 0) {
+    if ((await execa(gitCommand, [source.url, dest])).exitCode !== 0) {
       logger.error`Cloning Git template failed!`;
       process.exit(1);
     }
@@ -583,24 +586,27 @@ export default async function init(
   const cdpath = path.relative('.', dest);
   const pkgManager = await getPackageManager(dest, cliOptions);
   if (!cliOptions.skipInstall) {
-    shell.cd(dest);
+    process.chdir(dest);
     logger.info`Installing dependencies with name=${pkgManager}...`;
+    // ...
+
     if (
-      shell.exec(
-        pkgManager === 'yarn'
-          ? 'yarn'
-          : pkgManager === 'bun'
-          ? 'bun install'
-          : `${pkgManager} install --color always`,
-        {
-          env: {
-            ...process.env,
-            // Force coloring the output, since the command is invoked by
-            // shelljs, which is not an interactive shell
-            ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+      (
+        await execa.command(
+          pkgManager === 'yarn'
+            ? 'yarn'
+            : pkgManager === 'bun'
+            ? 'bun install'
+            : `${pkgManager} install --color always`,
+          {
+            env: {
+              ...process.env,
+              // Force coloring the output
+              ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+            },
           },
-        },
-      ).code !== 0
+        )
+      ).exitCode !== 0
     ) {
       logger.error('Dependency installation failed.');
       logger.info`The site directory has already been created, and you can retry by typing:

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
@@ -21,7 +26,6 @@ const config: Config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -67,6 +71,9 @@ const config: Config = {
   themeConfig: {
     // Replace with your project's social card
     image: 'img/docusaurus-social-card.jpg',
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
     navbar: {
       title: 'My Site',
       logo: {

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

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

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
@@ -26,7 +31,6 @@ const config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -75,6 +79,9 @@ const config = {
     ({
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
+      colorMode: {
+        respectPrefersColorScheme: true,
+      },
       navbar: {
         title: 'My Site',
         logo: {

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

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

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

@@ -2,40 +2,40 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+## Installation
 
-```
-$ yarn
+```bash
+yarn
 ```
 
-### Local Development
+## Local Development
 
-```
-$ yarn start
+```bash
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+## Build
 
-```
-$ yarn build
+```bash
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
 Using SSH:
 
-```
-$ USE_SSH=true yarn deploy
+```bash
+USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

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

@@ -1,12 +1,14 @@
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  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/create-docusaurus/templates/shared/docs/intro.md

@@ -14,7 +14,7 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
 
 ### What you'll need
 
-- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
+- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
   - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
 
 ## Generate a new site

packages/docusaurus-babel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/babel",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "Docusaurus package for Babel-related utils.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -36,15 +36,14 @@
     "@babel/preset-react": "^7.25.9",
     "@babel/preset-typescript": "^7.25.9",
     "@babel/runtime": "^7.25.9",
-    "@babel/runtime-corejs3": "^7.25.9",
     "@babel/traverse": "^7.25.9",
-    "@docusaurus/logger": "3.6.1",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "babel-plugin-dynamic-import-node": "^2.3.3",
     "fs-extra": "^11.1.1",
     "tslib": "^2.6.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   }
 }

packages/docusaurus-bundler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/bundler",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "Docusaurus util package to abstract the current bundler.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,25 +19,24 @@
   "license": "MIT",
   "dependencies": {
     "@babel/core": "^7.25.9",
-    "@docusaurus/babel": "3.6.1",
-    "@docusaurus/cssnano-preset": "3.6.1",
-    "@docusaurus/logger": "3.6.1",
-    "@docusaurus/types": "3.6.1",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/babel": "3.9.2",
+    "@docusaurus/cssnano-preset": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "babel-loader": "^9.2.1",
-    "clean-css": "^5.3.2",
+    "clean-css": "^5.3.3",
     "copy-webpack-plugin": "^11.0.0",
-    "css-loader": "^6.8.1",
+    "css-loader": "^6.11.0",
     "css-minimizer-webpack-plugin": "^5.0.1",
     "cssnano": "^6.1.2",
     "file-loader": "^6.2.0",
     "html-minifier-terser": "^7.2.0",
-    "mini-css-extract-plugin": "^2.9.1",
+    "mini-css-extract-plugin": "^2.9.2",
     "null-loader": "^4.0.1",
-    "postcss": "^8.4.26",
-    "postcss-loader": "^7.3.3",
-    "postcss-preset-env": "^10.1.0",
-    "react-dev-utils": "^12.0.1",
+    "postcss": "^8.5.4",
+    "postcss-loader": "^7.3.4",
+    "postcss-preset-env": "^10.2.1",
     "terser-webpack-plugin": "^5.3.9",
     "tslib": "^2.6.0",
     "url-loader": "^4.1.1",
@@ -56,6 +55,6 @@
     "@total-typescript/shoehorn": "^0.1.2"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   }
 }

packages/docusaurus-bundler/src/compiler.ts

@@ -7,7 +7,7 @@
 
 import {type Configuration} from 'webpack';
 import logger from '@docusaurus/logger';
-import formatWebpackMessages from 'react-dev-utils/formatWebpackMessages';
+import formatWebpackMessages from './legacy/formatWebpackMessages';
 import type webpack from 'webpack';
 import type {CurrentBundler} from '@docusaurus/types';
 

packages/docusaurus-bundler/src/currentBundler.ts

@@ -104,3 +104,46 @@ export async function getProgressBarPlugin({
 
   return WebpackBar;
 }
+
+export async function registerBundlerTracing({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): Promise<() => Promise<void>> {
+  if (currentBundler.name === 'rspack') {
+    const Rspack = await importRspack();
+
+    // See https://rspack.dev/contribute/development/profiling
+    // File can be opened with https://ui.perfetto.dev/
+    if (process.env.DOCUSAURUS_RSPACK_TRACE) {
+      // We use the env variable as the "filter" attribute
+      // See values here: https://rspack.dev/contribute/development/tracing#tracing-filter
+      let filter = process.env.DOCUSAURUS_RSPACK_TRACE;
+
+      if (filter === 'true' || filter === '1') {
+        // Default value recommended by the Rspack team
+        // It's also what the CLI uses for the "overview" preset:
+        // https://github.com/web-infra-dev/rspack/blob/v1.3.10/packages/rspack-cli/src/utils/profile.ts
+        filter = 'info';
+      }
+
+      await Rspack.experiments.globalTrace.register(
+        filter,
+        'perfetto',
+        './rspack-tracing.pftrace',
+      );
+
+      console.info(`Rspack tracing registered, filter=${filter}`);
+
+      return async () => {
+        await Rspack.experiments.globalTrace.cleanup();
+        console.log(`Rspack tracing cleaned up, filter=${filter}`);
+      };
+    }
+  }
+
+  // We don't support Webpack tracing at the moment
+  return async () => {
+    // noop
+  };
+}

packages/docusaurus-bundler/src/index.ts

@@ -12,6 +12,7 @@ export {
   getCSSExtractPlugin,
   getCopyPlugin,
   getProgressBarPlugin,
+  registerBundlerTracing,
 } from './currentBundler';
 
 export {getMinimizers} from './minification';

packages/docusaurus-bundler/src/legacy/formatWebpackMessages.js

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+// TODO Legacy CRA react-dev-utils package code
+//  This code was in CRA/react-dev-utils (deprecated in 2025)
+//  We just copied the code as-is to remove a fat/useless dependency subtree
+//  See https://github.com/facebook/docusaurus/pull/10956
+//  See https://github.com/facebook/create-react-app/blob/main/packages/react-dev-utils/formatWebpackMessages.js
+
+/* eslint-disable */
+
+const friendlySyntaxErrorLabel = 'Syntax error:';
+
+function isLikelyASyntaxError(message) {
+  return message.indexOf(friendlySyntaxErrorLabel) !== -1;
+}
+
+// Cleans up webpack error messages.
+function formatMessage(message) {
+  let lines = [];
+
+  if (typeof message === 'string') {
+    lines = message.split('\n');
+  } else if ('message' in message) {
+    lines = message['message'].split('\n');
+  } else if (Array.isArray(message)) {
+    message.forEach((message) => {
+      if ('message' in message) {
+        lines = message['message'].split('\n');
+      }
+    });
+  }
+
+  // Strip webpack-added headers off errors/warnings
+  // https://github.com/webpack/webpack/blob/master/lib/ModuleError.js
+  lines = lines.filter((line) => !/Module [A-z ]+\(from/.test(line));
+
+  // Transform parsing error into syntax error
+  // TODO: move this to our ESLint formatter?
+  lines = lines.map((line) => {
+    const parsingError = /Line (\d+):(?:(\d+):)?\s*Parsing error: (.+)$/.exec(
+      line,
+    );
+    if (!parsingError) {
+      return line;
+    }
+    const [, errorLine, errorColumn, errorMessage] = parsingError;
+    return `${friendlySyntaxErrorLabel} ${errorMessage} (${errorLine}:${errorColumn})`;
+  });
+
+  message = lines.join('\n');
+  // Smoosh syntax errors (commonly found in CSS)
+  message = message.replace(
+    /SyntaxError\s+\((\d+):(\d+)\)\s*(.+?)\n/g,
+    `${friendlySyntaxErrorLabel} $3 ($1:$2)\n`,
+  );
+  // Clean up export errors
+  message = message.replace(
+    /^.*export '(.+?)' was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$1' is not exported from '$2'.`,
+  );
+  message = message.replace(
+    /^.*export 'default' \(imported as '(.+?)'\) was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$2' does not contain a default export (imported as '$1').`,
+  );
+  message = message.replace(
+    /^.*export '(.+?)' \(imported as '(.+?)'\) was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$1' is not exported from '$3' (imported as '$2').`,
+  );
+  lines = message.split('\n');
+
+  // Remove leading newline
+  if (lines.length > 2 && lines[1].trim() === '') {
+    lines.splice(1, 1);
+  }
+  // Clean up file name
+  lines[0] = lines[0].replace(/^(.*) \d+:\d+-\d+$/, '$1');
+
+  // Cleans up verbose "module not found" messages for files and packages.
+  if (lines[1] && lines[1].indexOf('Module not found: ') === 0) {
+    lines = [
+      lines[0],
+      lines[1]
+        .replace('Error: ', '')
+        .replace('Module not found: Cannot find file:', 'Cannot find file:'),
+    ];
+  }
+
+  // Add helpful message for users trying to use Sass for the first time
+  if (lines[1] && lines[1].match(/Cannot find module.+sass/)) {
+    lines[1] = 'To import Sass files, you first need to install sass.\n';
+    lines[1] +=
+      'Run `npm install sass` or `yarn add sass` inside your workspace.';
+  }
+
+  message = lines.join('\n');
+  // Internal stacks are generally useless so we strip them... with the
+  // exception of stacks containing `webpack:` because they're normally
+  // from user code generated by webpack. For more information see
+  // https://github.com/facebook/create-react-app/pull/1050
+  message = message.replace(
+    /^\s*at\s((?!webpack:).)*:\d+:\d+[\s)]*(\n|$)/gm,
+    '',
+  ); // at ... ...:x:y
+  message = message.replace(/^\s*at\s<anonymous>(\n|$)/gm, ''); // at <anonymous>
+  lines = message.split('\n');
+
+  // Remove duplicated newlines
+  lines = lines.filter(
+    (line, index, arr) =>
+      index === 0 ||
+      line.trim() !== '' ||
+      line.trim() !== arr[index - 1].trim(),
+  );
+
+  // Reassemble the message
+  message = lines.join('\n');
+  return message.trim();
+}
+
+/**
+ * @param {import("webpack").Stats.ToJsonOutput} json.
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+module.exports = function formatWebpackMessages(json) {
+  const formattedErrors = json.errors.map(formatMessage);
+  const formattedWarnings = json.warnings.map(formatMessage);
+  const result = {errors: formattedErrors, warnings: formattedWarnings};
+  if (result.errors.some(isLikelyASyntaxError)) {
+    // If there are any syntax errors, show just them.
+    result.errors = result.errors.filter(isLikelyASyntaxError);
+  }
+  return result;
+};

packages/docusaurus-bundler/src/loaders/jsLoader.ts

@@ -28,7 +28,7 @@ async function createSwcJsLoaderFactory(): Promise<
   return ({isServer}) => {
     return {
       loader,
-      options: getOptions({isServer}),
+      options: getOptions({isServer, bundlerName: 'webpack'}),
     };
   };
 }
@@ -42,7 +42,7 @@ async function createRspackSwcJsLoaderFactory(): Promise<
   return ({isServer}) => {
     return {
       loader,
-      options: getOptions({isServer}),
+      options: getOptions({isServer, bundlerName: 'rspack'}),
     };
   };
 }

packages/docusaurus-bundler/src/minification.ts

@@ -142,7 +142,10 @@ async function getRspackMinimizers({
 }: MinimizersConfig): Promise<WebpackPluginInstance[]> {
   const rspack = getCurrentBundlerAsRspack({currentBundler});
   const getBrowserslistQueries = await importGetBrowserslistQueries();
-  const browserslistQueries = getBrowserslistQueries({isServer: false});
+  const browserslistQueries = getBrowserslistQueries({
+    isServer: false,
+    bundlerName: 'rspack',
+  });
   const swcJsMinimizerOptions = await importSwcJsMinimizerOptions();
   return [
     // See https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin

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,
-          removeEmptyAttributes: true,
+          removeRedundantAttributes: false,
+          removeEmptyAttributes: false,
+          sortAttributes: false,
+          sortClassName: false,
+
           removeScriptTypeAttributes: true,
           removeStyleLinkTypeAttributes: true,
           useShortDoctype: true,
@@ -80,12 +84,21 @@ async function getSwcMinifier(): Promise<HtmlMinifier> {
           // TODO maybe it's fine to only keep <!-- --> React comments?
           preserveComments: [],
 
+          // Keep <head> tag: important for social image crawlers like LinkedIn
+          // See https://github.com/swc-project/swc/issues/10994
+          tagOmission: 'keep-head-and-body',
+
           // Sorting these attributes (class) can lead to React hydration errors
           sortSpaceSeparatedAttributeValues: false,
           sortAttributes: false,
 
-          removeRedundantAttributes: 'all',
-          removeEmptyAttributes: true,
+          // When enabled => hydration error for className={"yt-lite "}
+          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.1",
+  "version": "3.9.2",
   "description": "Advanced cssnano preset for maximum optimization.",
   "main": "lib/index.js",
   "license": "MIT",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "cssnano-preset-advanced": "^6.1.2",
-    "postcss": "^8.4.38",
+    "postcss": "^8.5.4",
     "postcss-sort-media-queries": "^5.2.0",
     "tslib": "^2.6.0"
   },
@@ -26,6 +26,6 @@
     "to-vfile": "^6.1.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   }
 }

packages/docusaurus-cssnano-preset/src/index.ts

@@ -13,6 +13,9 @@ const preset: typeof advancedBasePreset = function preset(opts) {
   const advancedPreset = advancedBasePreset({
     autoprefixer: {add: false},
     discardComments: {removeAll: true},
+    // See CodeBlock custom line number bug: https://github.com/facebook/docusaurus/pull/11487
+    /* cSpell:ignore Idents */
+    reduceIdents: {counter: false},
     /* cSpell:ignore zindex */
     zindex: false,
     ...opts,
@@ -26,4 +29,5 @@ const preset: typeof advancedBasePreset = function preset(opts) {
   return advancedPreset;
 };
 
+// @ts-expect-error: TODO fix later
 export = preset;

packages/docusaurus-faster/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/faster",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "Docusaurus experimental package exposing new modern dependencies to make the build faster.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,18 +18,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/types": "3.6.1",
-    "@rspack/core": "^1.1.1",
+    "@docusaurus/types": "3.9.2",
+    "@rspack/core": "^1.5.0",
     "@swc/core": "^1.7.39",
-    "@swc/html": "^1.7.39",
+    "@swc/html": "^1.13.5",
     "browserslist": "^4.24.2",
     "lightningcss": "^1.27.0",
+    "semver": "^7.5.4",
     "swc-loader": "^0.2.6",
     "tslib": "^2.6.0",
     "webpack": "^5.95.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
   "peerDependencies": {
     "@docusaurus/types": "*"

packages/docusaurus-faster/src/index.ts

@@ -9,18 +9,22 @@ import Rspack from '@rspack/core';
 import * as lightningcss from 'lightningcss';
 import browserslist from 'browserslist';
 import {minify as swcHtmlMinifier} from '@swc/html';
+import semver from 'semver';
 import type {JsMinifyOptions, Options as SwcOptions} from '@swc/core';
+import type {CurrentBundler} from '@docusaurus/types';
 
 export const swcLoader = require.resolve('swc-loader');
 
 export const getSwcLoaderOptions = ({
   isServer,
+  bundlerName,
 }: {
   isServer: boolean;
+  bundlerName: CurrentBundler['name'];
 }): SwcOptions => {
   return {
     env: {
-      targets: getBrowserslistQueries({isServer}),
+      targets: getBrowserslistQueries({isServer, bundlerName}),
     },
     jsc: {
       parser: {
@@ -63,20 +67,53 @@ export function getSwcJsMinimizerOptions(): JsMinifyOptions {
   };
 }
 
+// TODO this is not accurate
+//  for Rspack we should read from the built-in browserslist data
+//  see https://github.com/facebook/docusaurus/pull/11496
+function getLastBrowserslistKnownNodeVersion(
+  bundlerName: CurrentBundler['name'],
+): string {
+  if (bundlerName === 'rspack') {
+    // TODO hardcoded value until Rspack exposes its Browserslist data
+    //  see https://github.com/facebook/docusaurus/pull/11496
+    return '22.0.0';
+  }
+  // browserslist('last 1 node versions')[0]!.replace('node ', '')
+  return browserslist.nodeVersions.at(-1)!;
+}
+
+function getMinVersion(v1: string, v2: string): string {
+  return semver.lt(v1, v2) ? v1 : v2;
+}
+
 // We need this because of Rspack built-in LightningCSS integration
 // See https://github.com/orgs/browserslist/discussions/846
 export function getBrowserslistQueries({
   isServer,
+  bundlerName,
 }: {
   isServer: boolean;
+  bundlerName: CurrentBundler['name'];
 }): string[] {
   if (isServer) {
-    return [`node ${process.versions.node}`];
+    // Escape hatch env variable
+    if (process.env.DOCUSAURUS_SERVER_NODE_TARGET) {
+      return [`node ${process.env.DOCUSAURUS_SERVER_NODE_TARGET}`];
+    }
+    // For server builds, we want to use the current Node version as target
+    // But we can't pass a target that Browserslist doesn't know about yet
+    const nodeTarget = getMinVersion(
+      process.versions.node,
+      getLastBrowserslistKnownNodeVersion(bundlerName),
+    );
+
+    return [`node ${nodeTarget}`];
   }
 
   const queries = browserslist.loadConfig({path: process.cwd()}) ?? [
     ...browserslist.defaults,
   ];
+
   return queries;
 }
 

packages/docusaurus-logger/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/logger",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "An encapsulated logger for semantically formatting console messages.",
   "main": "./lib/index.js",
   "repository": {
@@ -24,7 +24,7 @@
     "tslib": "^2.6.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   },
   "devDependencies": {
     "@types/supports-color": "^8.1.1"

packages/docusaurus-logger/src/perfLogger.ts

@@ -72,12 +72,22 @@ function createPerfLogger(): PerfLoggerAPI {
     }
   };
 
-  const formatMemory = (memory: Memory): string => {
-    const fmtHead = (bytes: number) =>
-      logger.cyan(`${(bytes / 1000000).toFixed(0)}mb`);
+  const formatBytesToMb = (bytes: number) =>
+    logger.cyan(`${(bytes / 1024 / 1024).toFixed(0)}mb`);
+
+  const formatMemoryDelta = (memory: Memory): string => {
     return logger.dim(
-      `(${fmtHead(memory.before.heapUsed)} -> ${fmtHead(
+      `(Heap ${formatBytesToMb(memory.before.heapUsed)} -> ${formatBytesToMb(
         memory.after.heapUsed,
+      )} / Total ${formatBytesToMb(memory.after.heapTotal)})`,
+    );
+  };
+
+  const formatMemoryCurrent = (): string => {
+    const memory = getMemory();
+    return logger.dim(
+      `(Heap ${formatBytesToMb(memory.heapUsed)} / Total ${formatBytesToMb(
+        memory.heapTotal,
       )})`,
     );
   };
@@ -103,7 +113,7 @@ function createPerfLogger(): PerfLoggerAPI {
     console.log(
       `${PerfPrefix}${formatStatus(error)} ${label} - ${formatDuration(
         duration,
-      )} - ${formatMemory(memory)}`,
+      )} - ${formatMemoryDelta(memory)}`,
     );
   };
 
@@ -114,12 +124,24 @@ function createPerfLogger(): PerfLoggerAPI {
       },
     });
 
-  const end: PerfLoggerAPI['end'] = (label) => {
-    const {
-      duration,
-      detail: {memoryUsage},
-    } = performance.measure(label);
+  const readMark = (label: string) => {
+    const startMark = performance.getEntriesByName(
+      label,
+      'mark',
+    )?.[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,
@@ -132,7 +154,9 @@ function createPerfLogger(): PerfLoggerAPI {
   };
 
   const log: PerfLoggerAPI['log'] = (label: string) =>
-    console.log(`${PerfPrefix} ${applyParentPrefix(label)}`);
+    console.log(
+      `${PerfPrefix} ${applyParentPrefix(label)} - ${formatMemoryCurrent()}`,
+    );
 
   const async: PerfLoggerAPI['async'] = async (label, asyncFn) => {
     const finalLabel = applyParentPrefix(label);

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "3.6.1",
+  "version": "3.9.2",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,16 +18,16 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.1",
-    "@docusaurus/utils": "3.6.1",
-    "@docusaurus/utils-validation": "3.6.1",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@mdx-js/mdx": "^3.0.0",
     "@slorber/remark-comment": "^1.0.0",
     "escape-html": "^1.0.3",
     "estree-util-value-to-estree": "^3.0.1",
     "file-loader": "^6.2.0",
     "fs-extra": "^11.1.1",
-    "image-size": "^1.0.2",
+    "image-size": "^2.0.2",
     "mdast-util-mdx": "^3.0.0",
     "mdast-util-to-string": "^4.0.0",
     "rehype-raw": "^7.0.0",
@@ -44,7 +44,7 @@
     "webpack": "^5.88.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.6.1",
+    "@docusaurus/types": "3.9.2",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",
@@ -58,10 +58,10 @@
     "unist-util-remove-position": "^5.0.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.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/processor.ts

@@ -22,8 +22,9 @@ import type {WebpackCompilerName} from '@docusaurus/utils';
 import type {MDXFrontMatter} from './frontMatter';
 import type {Options} from './options';
 import type {AdmonitionOptions} from './remark/admonitions';
-
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {PluginOptions as ResolveMarkdownLinksOptions} from './remark/resolveMarkdownLinks';
+import type {PluginOptions as TransformLinksOptions} from './remark/transformLinks';
+import type {PluginOptions as TransformImageOptions} from './remark/transformImage';
 import type {ProcessorOptions} from '@mdx-js/mdx';
 
 // TODO as of April 2023, no way to import/re-export this ESM type easily :/
@@ -94,7 +95,7 @@ async function createProcessorFactory() {
         headings,
         {anchorsMaintainCase: options.markdownConfig.anchors.maintainCase},
       ],
-      emoji,
+      ...(options.markdownConfig.emoji ? [emoji] : []),
       toc,
     ];
   }
@@ -123,13 +124,19 @@ async function createProcessorFactory() {
         {
           staticDirs: options.staticDirs,
           siteDir: options.siteDir,
-        },
+          onBrokenMarkdownImages:
+            options.markdownConfig.hooks.onBrokenMarkdownImages,
+        } satisfies TransformImageOptions,
       ],
       // TODO merge this with transformLinks?
       options.resolveMarkdownLink
         ? [
             resolveMarkdownLinks,
-            {resolveMarkdownLink: options.resolveMarkdownLink},
+            {
+              resolveMarkdownLink: options.resolveMarkdownLink,
+              onBrokenMarkdownLinks:
+                options.markdownConfig.hooks.onBrokenMarkdownLinks,
+            } satisfies ResolveMarkdownLinksOptions,
           ]
         : undefined,
       [
@@ -137,7 +144,9 @@ async function createProcessorFactory() {
         {
           staticDirs: options.staticDirs,
           siteDir: options.siteDir,
-        },
+          onBrokenMarkdownLinks:
+            options.markdownConfig.hooks.onBrokenMarkdownLinks,
+        } satisfies TransformLinksOptions,
       ],
       gfm,
       options.markdownConfig.mdx1Compat.comments ? comment : null,

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

@@ -4,10 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer, Plugin} from 'unified';
-
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {ContainerDirective} from 'mdast-util-directive';
 import type {Parent, Root} from 'mdast';
 

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

@@ -4,11 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer, Plugin} from 'unified';
 import type {Heading, Parent, Root} from 'mdast';
-
-// @ts-expect-error: ES support...
 import type {MdxJsxFlowElement} from 'mdast-util-mdx';
 
 interface PluginOptions {

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

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 
 import type {Root} from 'mdast';

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

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 
 import type {Root} from 'mdast';

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

@@ -8,7 +8,6 @@
 /* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
 
 import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Plugin, Transformer} from 'unified';
 import type {Root, Text} from 'mdast';
 

packages/docusaurus-mdx-loader/src/remark/mdx1Compat/codeCompatPlugin.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer, Plugin} from 'unified';
 import type {Root} from 'mdast';
 
@@ -26,6 +25,7 @@ const plugin: Plugin<unknown[], Root> = function plugin(): Transformer<Root> {
       node.data.hProperties = node.data.hProperties || {};
       node.data.hProperties.metastring = node.meta;
 
+      // TODO Docusaurus v4: remove special case
       // Retrocompatible support for live codeblock metastring
       // Not really the appropriate place to handle that :s
       node.data.hProperties.live = node.meta?.split(' ').includes('live');

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

@@ -7,7 +7,6 @@
 
 import {transformNode} from '../utils';
 
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 import type {Root} from 'mdast';
 

packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/index.test.ts

@@ -5,22 +5,47 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {jest} from '@jest/globals';
+import * as path from 'path';
 import plugin from '..';
 import type {PluginOptions} from '../index';
 
-async function process(content: string) {
-  const {remark} = await import('remark');
+const siteDir = __dirname;
 
-  const options: PluginOptions = {
-    resolveMarkdownLink: ({linkPathname}) => `/RESOLVED---${linkPathname}`,
+const DefaultTestOptions: PluginOptions = {
+  resolveMarkdownLink: ({linkPathname}) => `/RESOLVED---${linkPathname}`,
+  onBrokenMarkdownLinks: 'throw',
+};
+
+async function process(content: string, optionsInput?: Partial<PluginOptions>) {
+  const options = {
+    ...DefaultTestOptions,
+    ...optionsInput,
   };
 
-  const result = await remark().use(plugin, options).process(content);
+  const {remark} = await import('remark');
+
+  const result = await remark()
+    .use(plugin, options)
+    .process({
+      value: content,
+      path: path.posix.join(siteDir, 'docs', 'myFile.mdx'),
+    });
 
   return result.value;
 }
 
 describe('resolveMarkdownLinks remark plugin', () => {
+  it('accepts non-md link', async () => {
+    /* language=markdown */
+    const content = `[link1](link1)`;
+    const result = await process(content);
+    expect(result).toMatchInlineSnapshot(`
+        "[link1](link1)
+        "
+      `);
+  });
+
   it('resolves Markdown and MDX links', async () => {
     /* language=markdown */
     const content = `[link1](link1.mdx)
@@ -157,4 +182,212 @@ this is a code block
       "
     `);
   });
+
+  describe('onBrokenMarkdownLinks', () => {
+    const warnMock = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    beforeEach(() => {
+      warnMock.mockClear();
+    });
+
+    async function processResolutionErrors(
+      content: string,
+      onBrokenMarkdownLinks: PluginOptions['onBrokenMarkdownLinks'] = 'throw',
+    ) {
+      return process(content, {
+        resolveMarkdownLink: () => null,
+        onBrokenMarkdownLinks,
+      });
+    }
+
+    describe('throws', () => {
+      it('for unresolvable mdx link', async () => {
+        /* language=markdown */
+        const content = `[link1](link1.mdx)`;
+
+        await expect(() => processResolutionErrors(content)).rejects
+          .toThrowErrorMatchingInlineSnapshot(`
+          "Markdown link with URL \`link1.mdx\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (1:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.
+          To ignore this error, use the \`siteConfig.markdown.hooks.onBrokenMarkdownLinks\` option, or apply the \`pathname://\` protocol to the broken link URLs."
+        `);
+      });
+
+      it('for unresolvable md link', async () => {
+        /* language=markdown */
+        const content = `[link1](link1.md)`;
+
+        await expect(() => processResolutionErrors(content)).rejects
+          .toThrowErrorMatchingInlineSnapshot(`
+          "Markdown link with URL \`link1.md\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (1:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.
+          To ignore this error, use the \`siteConfig.markdown.hooks.onBrokenMarkdownLinks\` option, or apply the \`pathname://\` protocol to the broken link URLs."
+        `);
+      });
+    });
+
+    describe('warns', () => {
+      it('for unresolvable md and mdx link', async () => {
+        /* language=markdown */
+        const content = `
+[link1](link1.mdx)
+
+[link2](link2)
+
+[link3](dir/link3.md)
+
+[link 4](/link/4)
+      `;
+
+        const result = await processResolutionErrors(content, 'warn');
+
+        expect(result).toMatchInlineSnapshot(`
+                  "[link1](link1.mdx)
+
+                  [link2](link2)
+
+                  [link3](dir/link3.md)
+
+                  [link 4](/link/4)
+                  "
+              `);
+
+        expect(warnMock).toHaveBeenCalledTimes(2);
+        expect(warnMock.mock.calls).toMatchInlineSnapshot(`
+          [
+            [
+              "[WARNING] Markdown link with URL \`link1.mdx\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (2:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.",
+            ],
+            [
+              "[WARNING] Markdown link with URL \`dir/link3.md\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (6:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.",
+            ],
+          ]
+        `);
+      });
+
+      it('for unresolvable md and mdx link - with recovery', async () => {
+        /* language=markdown */
+        const content = `
+[link1](link1.mdx)
+
+[link2](link2)
+
+[link3](dir/link3.md?query#hash)
+
+[link 4](/link/4)
+      `;
+
+        const result = await processResolutionErrors(content, (params) => {
+          console.warn(`onBrokenMarkdownLinks called with`, params);
+          // We can alter the AST Node
+          params.node.title = 'fixed link title';
+          params.node.url = 'ignored, less important than returned value';
+          // Or return a new URL
+          return `/recovered-link`;
+        });
+
+        expect(result).toMatchInlineSnapshot(`
+          "[link1](/recovered-link "fixed link title")
+
+          [link2](link2)
+
+          [link3](/recovered-link "fixed link title")
+
+          [link 4](/link/4)
+          "
+        `);
+
+        expect(warnMock).toHaveBeenCalledTimes(2);
+        expect(warnMock.mock.calls).toMatchInlineSnapshot(`
+          [
+            [
+              "onBrokenMarkdownLinks called with",
+              {
+                "node": {
+                  "children": [
+                    {
+                      "position": {
+                        "end": {
+                          "column": 7,
+                          "line": 2,
+                          "offset": 7,
+                        },
+                        "start": {
+                          "column": 2,
+                          "line": 2,
+                          "offset": 2,
+                        },
+                      },
+                      "type": "text",
+                      "value": "link1",
+                    },
+                  ],
+                  "position": {
+                    "end": {
+                      "column": 19,
+                      "line": 2,
+                      "offset": 19,
+                    },
+                    "start": {
+                      "column": 1,
+                      "line": 2,
+                      "offset": 1,
+                    },
+                  },
+                  "title": "fixed link title",
+                  "type": "link",
+                  "url": "/recovered-link",
+                },
+                "sourceFilePath": "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx",
+                "url": "link1.mdx",
+              },
+            ],
+            [
+              "onBrokenMarkdownLinks called with",
+              {
+                "node": {
+                  "children": [
+                    {
+                      "position": {
+                        "end": {
+                          "column": 7,
+                          "line": 6,
+                          "offset": 43,
+                        },
+                        "start": {
+                          "column": 2,
+                          "line": 6,
+                          "offset": 38,
+                        },
+                      },
+                      "type": "text",
+                      "value": "link3",
+                    },
+                  ],
+                  "position": {
+                    "end": {
+                      "column": 33,
+                      "line": 6,
+                      "offset": 69,
+                    },
+                    "start": {
+                      "column": 1,
+                      "line": 6,
+                      "offset": 37,
+                    },
+                  },
+                  "title": "fixed link title",
+                  "type": "link",
+                  "url": "/recovered-link",
+                },
+                "sourceFilePath": "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx",
+                "url": "dir/link3.md?query#hash",
+              },
+            ],
+          ]
+        `);
+      });
+    });
+  });
 });

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

@@ -8,12 +8,18 @@
 import {
   parseLocalURLPath,
   serializeURLPath,
+  toMessageRelativeFilePath,
   type URLPath,
 } from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import {formatNodePositionExtraMessage} from '../utils';
 import type {Plugin, Transformer} from 'unified';
 import type {Definition, Link, Root} from 'mdast';
+import type {
+  MarkdownConfig,
+  OnBrokenMarkdownLinksFunction,
+} from '@docusaurus/types';
 
 type ResolveMarkdownLinkParams = {
   /**
@@ -33,6 +39,33 @@ export type ResolveMarkdownLink = (
 
 export interface PluginOptions {
   resolveMarkdownLink: ResolveMarkdownLink;
+  onBrokenMarkdownLinks: MarkdownConfig['hooks']['onBrokenMarkdownLinks'];
+}
+
+function asFunction(
+  onBrokenMarkdownLinks: PluginOptions['onBrokenMarkdownLinks'],
+): OnBrokenMarkdownLinksFunction {
+  if (typeof onBrokenMarkdownLinks === 'string') {
+    const extraHelp =
+      onBrokenMarkdownLinks === 'throw'
+        ? logger.interpolate`\nTo ignore this error, use the code=${'siteConfig.markdown.hooks.onBrokenMarkdownLinks'} option, or apply the code=${'pathname://'} protocol to the broken link URLs.`
+        : '';
+    return ({sourceFilePath, url: linkUrl, node}) => {
+      const relativePath = toMessageRelativeFilePath(sourceFilePath);
+      logger.report(
+        onBrokenMarkdownLinks,
+      )`Markdown link with URL code=${linkUrl} in source file path=${relativePath}${formatNodePositionExtraMessage(
+        node,
+      )} couldn't be resolved.
+Make sure it references a local Markdown file that exists within the current plugin.${extraHelp}`;
+    };
+  } else {
+    return (params) =>
+      onBrokenMarkdownLinks({
+        ...params,
+        sourceFilePath: toMessageRelativeFilePath(params.sourceFilePath),
+      });
+  }
 }
 
 const HAS_MARKDOWN_EXTENSION = /\.mdx?$/i;
@@ -58,10 +91,15 @@ function parseMarkdownLinkURLPath(link: string): URLPath | null {
  * This is exposed as "data.contentTitle" to the processed vfile
  * Also gives the ability to strip that content title (used for the blog plugin)
  */
+// TODO merge this plugin with "transformLinks"
+//  in general we'd want to avoid traversing multiple times the same AST
 const plugin: Plugin<PluginOptions[], Root> = function plugin(
   options,
 ): Transformer<Root> {
   const {resolveMarkdownLink} = options;
+
+  const onBrokenMarkdownLinks = asFunction(options.onBrokenMarkdownLinks);
+
   return async (root, file) => {
     const {visit} = await import('unist-util-visit');
 
@@ -72,18 +110,26 @@ const plugin: Plugin<PluginOptions[], Root> = function plugin(
         return;
       }
 
+      const sourceFilePath = file.path;
+
       const permalink = resolveMarkdownLink({
-        sourceFilePath: file.path,
+        sourceFilePath,
         linkPathname: linkURLPath.pathname,
       });
 
       if (permalink) {
         // This reapplies the link ?qs#hash part to the resolved pathname
-        const resolvedUrl = serializeURLPath({
+        link.url = serializeURLPath({
           ...linkURLPath,
           pathname: permalink,
         });
-        link.url = resolvedUrl;
+      } else {
+        link.url =
+          onBrokenMarkdownLinks({
+            url: link.url,
+            sourceFilePath,
+            node: link,
+          }) ?? link.url;
       }
     });
   };

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/utils.test.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 {toHeadingHTMLValue} from '../utils';
+import type {Heading} from 'mdast';
+
+describe('toHeadingHTMLValue', () => {
+  async function convert(heading: Heading): Promise<string> {
+    const {toString} = await import('mdast-util-to-string');
+    return toHeadingHTMLValue(heading, toString);
+  }
+
+  it('converts a simple heading', async () => {
+    const heading: Heading = {
+      type: 'heading',
+      depth: 2,
+      children: [
+        {
+          type: 'text',
+          value: 'Some heading text',
+        },
+      ],
+    };
+
+    await expect(convert(heading)).resolves.toMatchInlineSnapshot(
+      `"Some heading text"`,
+    );
+  });
+
+  it('converts a heading with b tag', async () => {
+    const heading: Heading = {
+      type: 'heading',
+      depth: 2,
+      children: [
+        {
+          type: 'mdxJsxTextElement',
+          name: 'b',
+          attributes: [],
+          children: [
+            {
+              type: 'text',
+              value: 'Some title',
+            },
+          ],
+        },
+      ],
+    };
+
+    await expect(convert(heading)).resolves.toMatchInlineSnapshot(
+      `"<b>Some title</b>"`,
+    );
+  });
+
+  it('converts a heading with span tag + className', async () => {
+    const heading: Heading = {
+      type: 'heading',
+      depth: 2,
+      children: [
+        {
+          type: 'mdxJsxTextElement',
+          name: 'span',
+          attributes: [
+            {
+              type: 'mdxJsxAttribute',
+              name: 'className',
+              value: 'my-class',
+            },
+          ],
+          children: [
+            {
+              type: 'text',
+              value: 'Some title',
+            },
+          ],
+        },
+      ],
+    };
+
+    await expect(convert(heading)).resolves.toMatchInlineSnapshot(
+      `"<span class="my-class">Some title</span>"`,
+    );
+  });
+
+  it('converts a heading - remove img tag', async () => {
+    const heading: Heading = {
+      type: 'heading',
+      depth: 2,
+      children: [
+        {
+          type: 'mdxJsxTextElement',
+          name: 'img',
+          attributes: [
+            {
+              type: 'mdxJsxAttribute',
+              name: 'src',
+              value: '/img/slash-introducing.svg',
+            },
+            {
+              type: 'mdxJsxAttribute',
+              name: 'height',
+              value: '32',
+            },
+            {
+              type: 'mdxJsxAttribute',
+              name: 'alt',
+              value: 'test',
+            },
+          ],
+          children: [],
+        },
+        {
+          type: 'text',
+          value: ' Some title',
+        },
+      ],
+    };
+
+    await expect(convert(heading)).resolves.toMatchInlineSnapshot(
+      `"Some title"`,
+    );
+  });
+});

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

@@ -14,13 +14,8 @@ import {
   isNamedExport,
 } from './utils';
 import type {Heading, Root} from 'mdast';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Plugin, Transformer} from 'unified';
-import type {
-  MdxjsEsm,
-  MdxJsxFlowElement,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-} from 'mdast-util-mdx';
+import type {MdxjsEsm, MdxJsxFlowElement} from 'mdast-util-mdx';
 import type {TOCItems} from './types';
 import type {ImportDeclaration} from 'estree';