test(reading-time): Unit tests for calculating reading time (#11116)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.cspell.json

@@ -21,11 +21,14 @@
   ],
   "ignorePaths": [
     "CHANGELOG.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,5 +1,7 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "customizations": {
+    "vscode": {
       "settings": {
         "[typescript]": {
           "editor.defaultFormatter": "esbenp.prettier-vscode",
@@ -19,14 +21,16 @@
         "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,
@@ -296,7 +298,7 @@ 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,
@@ -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

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

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

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

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

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

.github/workflows/build-perf.yml

@@ -43,12 +43,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Track build size changes
-        uses: preactjs/compressed-size-action@6fa0e7ca017120c754863b31123c5ee2860fd434 # v2
+        uses: preactjs/compressed-size-action@946a292cd35bd1088e0d7eb92b69d1a8d5b5d76a # v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           build-script: build:website:fast
@@ -75,7 +75,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
@@ -85,14 +85,15 @@ 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'  }}
 
       # 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'  }}
 

.github/workflows/canary-release.yml

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

.github/workflows/continuous-releases.yml

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

.github/workflows/dependency-review.yml

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

.github/workflows/lighthouse-report.yml

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

.github/workflows/lint.yml

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

.github/workflows/showcase-test.yml

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

.github/workflows/tests-e2e.yml

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

.github/workflows/tests-swizzle.yml

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

.github/workflows/tests-windows.yml

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

.github/workflows/tests.yml

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

.gitignore

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

.prettierignore

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

CHANGELOG.md

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

admin/new.docusaurus.io/package.json

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

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"
@@ -52,7 +54,8 @@ git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 cd ..
 
 # Build skeleton website with new version
-npm_config_registry="$CUSTOM_REGISTRY_URL" npx create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+npm_config_registry="$CUSTOM_REGISTRY_URL" npx --yes --loglevel silly create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+
 
 # Stop Docker container
 if [[ -z "${KEEP_CONTAINER:-true}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then

admin/test-bad-package/README.mdx

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

admin/test-bad-package/package.json

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

argos/package.json

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

argos/tests/screenshot.spec.ts

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

examples/README.md

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

examples/classic-typescript/README.md

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

examples/classic-typescript/package.json

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

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

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

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

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

examples/classic-typescript/tsconfig.json

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

examples/classic/README.md

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

examples/classic/package.json

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

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.1",
+  "version": "3.7.0",
   "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",
@@ -50,7 +52,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 +61,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 +85,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 +100,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 +114,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 +126,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.7.0",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,14 +22,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.1",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/utils": "3.7.0",
     "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"
   },

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 hasYarn = (await execa.command('yarn --version')).exitCode === 0;
-  const hasPnpm = shell.exec('pnpm --version', {silent: true}).code === 0;
+  const hasPnpm = (await execa.command('pnpm --version')).exitCode === 0;
-  const hasBun = shell.exec('bun --version', {silent: true}).code === 0;
+  const hasBun = (await execa.command('bun --version')).exitCode === 0;
 
   if (!hasYarn && !hasPnpm && !hasBun) {
     return 'npm';
@@ -530,10 +533,7 @@ export default async function init(
 
   if (source.type === 'git') {
     const gitCommand = await getGitCommand(source.strategy);
-    const gitCloneCommand = `${gitCommand} ${escapeShellArg(
+    if ((await execa(gitCommand, [source.url, dest])).exitCode !== 0) {
-      source.url,
-    )} ${escapeShellArg(dest)}`;
-    if (shell.exec(gitCloneCommand).code !== 0) {
       logger.error`Cloning Git template failed!`;
       process.exit(1);
     }
@@ -583,10 +583,13 @@ 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(
+      (
+        await execa.command(
           pkgManager === 'yarn'
             ? 'yarn'
             : pkgManager === 'bun'
@@ -595,12 +598,12 @@ export default async function init(
           {
             env: {
               ...process.env,
-            // Force coloring the output, since the command is invoked by
+              // Force coloring the output
-            // shelljs, which is not an interactive shell
               ...(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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

packages/docusaurus-babel/package.json

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

packages/docusaurus-bundler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/bundler",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "description": "Docusaurus util package to abstract the current bundler.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,11 +19,11 @@
   "license": "MIT",
   "dependencies": {
     "@babel/core": "^7.25.9",
-    "@docusaurus/babel": "3.6.1",
+    "@docusaurus/babel": "3.7.0",
-    "@docusaurus/cssnano-preset": "3.6.1",
+    "@docusaurus/cssnano-preset": "3.7.0",
-    "@docusaurus/logger": "3.6.1",
+    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/types": "3.6.1",
+    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/utils": "3.7.0",
     "babel-loader": "^9.2.1",
     "clean-css": "^5.3.2",
     "copy-webpack-plugin": "^11.0.0",
@@ -37,7 +37,6 @@
     "postcss": "^8.4.26",
     "postcss-loader": "^7.3.3",
     "postcss-preset-env": "^10.1.0",
-    "react-dev-utils": "^12.0.1",
     "terser-webpack-plugin": "^5.3.9",
     "tslib": "^2.6.0",
     "url-loader": "^4.1.1",

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/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/minifyHtml.ts

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

packages/docusaurus-cssnano-preset/package.json

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

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

@@ -26,4 +26,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.7.0",
   "description": "Docusaurus experimental package exposing new modern dependencies to make the build faster.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/types": "3.6.1",
+    "@docusaurus/types": "3.7.0",
-    "@rspack/core": "^1.1.1",
+    "@rspack/core": "^1.3.3",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",

packages/docusaurus-faster/src/index.ts

@@ -11,6 +11,16 @@ import browserslist from 'browserslist';
 import {minify as swcHtmlMinifier} from '@swc/html';
 import type {JsMinifyOptions, Options as SwcOptions} from '@swc/core';
 
+// See https://rspack.dev/contribute/development/profiling
+// File can be opened with https://ui.perfetto.dev/
+if (process.env.DOCUSAURUS_RSPACK_TRACE) {
+  Rspack.experiments.globalTrace.register(
+    'trace',
+    'chrome',
+    './rspack-tracing.json',
+  );
+}
+
 export const swcLoader = require.resolve('swc-loader');
 
 export const getSwcLoaderOptions = ({

packages/docusaurus-logger/package.json

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

packages/docusaurus-logger/src/perfLogger.ts

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

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "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/logger": "3.7.0",
-    "@docusaurus/utils": "3.6.1",
+    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-validation": "3.6.1",
+    "@docusaurus/utils-validation": "3.7.0",
     "@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.7.0",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",
@@ -58,8 +58,8 @@
     "unist-util-remove-position": "^5.0.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
+    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
     "node": ">=18.0"

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

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

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

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

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

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

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

@@ -22,8 +22,6 @@ 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 {ProcessorOptions} from '@mdx-js/mdx';
 
 // TODO as of April 2023, no way to import/re-export this ESM type easily :/

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/index.ts

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

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 {
+import type {MdxjsEsm, MdxJsxFlowElement} from 'mdast-util-mdx';
-  MdxjsEsm,
-  MdxJsxFlowElement,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-} from 'mdast-util-mdx';
 import type {TOCItems} from './types';
 import type {ImportDeclaration} from 'estree';
 

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

@@ -5,11 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {toValue} from '../utils';
+import escapeHtml from 'escape-html';
-import type {Node} from 'unist';
+import type {Node, Parent} from 'unist';
 import type {
   MdxjsEsm,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+  MdxJsxAttribute,
+  MdxJsxTextElement,
 } from 'mdast-util-mdx';
 import type {TOCHeading, TOCItem, TOCItems, TOCSlice} from './types';
 import type {
@@ -18,6 +19,7 @@ import type {
   ImportDeclaration,
   ImportSpecifier,
 } from 'estree';
+import type {Heading, PhrasingContent} from 'mdast';
 
 export function getImportDeclarations(program: Program): ImportDeclaration[] {
   return program.body.filter(
@@ -121,7 +123,7 @@ export async function createTOCExportNodeAST({
     const {toString} = await import('mdast-util-to-string');
     const {valueToEstree} = await import('estree-util-value-to-estree');
     const value: TOCItem = {
-      value: toValue(heading, toString),
+      value: toHeadingHTMLValue(heading, toString),
       id: heading.data!.id!,
       level: heading.depth,
     };
@@ -175,3 +177,73 @@ export async function createTOCExportNodeAST({
     },
   };
 }
+
+function stringifyChildren(
+  node: Parent,
+  toString: (param: unknown) => string, // TODO temporary, due to ESM
+): string {
+  return (node.children as PhrasingContent[])
+    .map((item) => toHeadingHTMLValue(item, toString))
+    .join('')
+    .trim();
+}
+
+// TODO This is really a workaround, and not super reliable
+// For now we only support serializing tagName, className and content
+// Can we implement the TOC with real JSX nodes instead of html strings later?
+function mdxJsxTextElementToHtml(
+  element: MdxJsxTextElement,
+  toString: (param: unknown) => string, // TODO temporary, due to ESM
+): string {
+  const tag = element.name;
+
+  // See https://github.com/facebook/docusaurus/issues/11003#issuecomment-2733925363
+  if (tag === 'img') {
+    return '';
+  }
+
+  const attributes = element.attributes.filter(
+    (child): child is MdxJsxAttribute => child.type === 'mdxJsxAttribute',
+  );
+
+  const classAttribute =
+    attributes.find((attr) => attr.name === 'className') ??
+    attributes.find((attr) => attr.name === 'class');
+
+  const classAttributeString = classAttribute
+    ? `class="${escapeHtml(String(classAttribute.value))}"`
+    : ``;
+
+  const allAttributes = classAttributeString ? ` ${classAttributeString}` : '';
+
+  const content = stringifyChildren(element, toString);
+
+  return `<${tag}${allAttributes}>${content}</${tag}>`;
+}
+
+export function toHeadingHTMLValue(
+  node: PhrasingContent | Heading | MdxJsxTextElement,
+  toString: (param: unknown) => string, // TODO temporary, due to ESM
+): string {
+  switch (node.type) {
+    case 'mdxJsxTextElement': {
+      return mdxJsxTextElementToHtml(node as MdxJsxTextElement, toString);
+    }
+    case 'text':
+      return escapeHtml(node.value);
+    case 'heading':
+      return stringifyChildren(node, toString);
+    case 'inlineCode':
+      return `<code>${escapeHtml(node.value)}</code>`;
+    case 'emphasis':
+      return `<em>${stringifyChildren(node, toString)}</em>`;
+    case 'strong':
+      return `<strong>${stringifyChildren(node, toString)}</strong>`;
+    case 'delete':
+      return `<del>${stringifyChildren(node, toString)}</del>`;
+    case 'link':
+      return stringifyChildren(node, toString);
+    default:
+      return toString(node);
+  }
+}

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

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

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

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

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

@@ -8,7 +8,6 @@
 import path from 'path';
 import url from 'url';
 import fs from 'fs-extra';
-import {promisify} from 'util';
 import {
   toMessageRelativeFilePath,
   posixPath,
@@ -17,12 +16,10 @@ import {
   getFileLoaderUtils,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
-import sizeOf from 'image-size';
+import {imageSizeFromFile} from 'image-size/fromFile';
 import logger from '@docusaurus/logger';
 import {assetRequireAttributeValue, transformNode} from '../utils';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Plugin, Transformer} from 'unified';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {MdxJsxTextElement} from 'mdast-util-mdx';
 import type {Image, Root} from 'mdast';
 import type {Parent} from 'unist';
@@ -82,7 +79,7 @@ async function toImageRequireNode(
   }
 
   try {
-    const size = (await promisify(sizeOf)(imagePath))!;
+    const size = (await imageSizeFromFile(imagePath))!;
     if (size.width) {
       attributes.push({
         type: 'mdxJsxAttribute',
@@ -98,6 +95,7 @@ async function toImageRequireNode(
       });
     }
   } catch (err) {
+    console.error(err);
     // Workaround for https://github.com/yarnpkg/berry/pull/3889#issuecomment-1034469784
     // TODO remove this check once fixed in Yarn PnP
     if (!process.versions.pnp) {
@@ -152,10 +150,7 @@ async function getImageAbsolutePath(
     return imageFilePath;
   }
   // relative paths are resolved against the source file's folder
-  const imageFilePath = path.join(
+  const imageFilePath = path.join(path.dirname(filePath), imagePath);
-    path.dirname(filePath),
-    decodeURIComponent(imagePath),
-  );
   await ensureImageFileExist(imageFilePath, filePath);
   return imageFilePath;
 }
@@ -180,9 +175,14 @@ async function processImageNode(target: Target, context: Context) {
     return;
   }
 
+  // We decode it first because Node Url.pathname is always encoded
+  // while the image file-system path are not.
+  // See https://github.com/facebook/docusaurus/discussions/10720
+  const decodedPathname = decodeURIComponent(parsedUrl.pathname);
+
   // We try to convert image urls without protocol to images with require calls
   // going through webpack ensures that image assets exist at build time
-  const imagePath = await getImageAbsolutePath(parsedUrl.pathname, context);
+  const imagePath = await getImageAbsolutePath(decodedPathname, context);
   await toImageRequireNode(target, imagePath, context);
 }
 

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

@@ -17,9 +17,7 @@ import {
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import {assetRequireAttributeValue, transformNode} from '../utils';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Plugin, Transformer} from 'unified';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {MdxJsxTextElement} from 'mdast-util-mdx';
 import type {Parent} from 'unist';
 import type {Link, Literal, Root} from 'mdast';

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

@@ -10,14 +10,9 @@ import logger from '@docusaurus/logger';
 import {posixPath} from '@docusaurus/utils';
 import {transformNode} from '../utils';
 import type {Root} from 'mdast';
-
+import type {Parent} from 'unist';
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {Transformer, Processor, Plugin} from 'unified';
-import type {Transformer, Processor, Parent, Plugin} from 'unified';
+import type {Directives, TextDirective} from 'mdast-util-directive';
-import type {
-  Directives,
-  TextDirective,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-} from 'mdast-util-directive';
 
 type DirectiveType = Directives['type'];
 
@@ -133,10 +128,8 @@ const plugin: Plugin<unknown[], Root> = function plugin(
 
     const unusedDirectives: Directives[] = [];
 
-    visit<Parent, DirectiveType[]>(
+    // @ts-expect-error: TODO fix type
-      tree,
+    visit<Parent, Directives>(tree, directiveTypes, (directive: Directives) => {
-      directiveTypes,
-      (directive: Directives) => {
       // If directive data is set (hName/hProperties set by admonitions)
       // this usually means the directive has been handled by another plugin
       if (isUnusedDirective(directive)) {
@@ -146,8 +139,7 @@ const plugin: Plugin<unknown[], Root> = function plugin(
           unusedDirectives.push(directive);
         }
       }
-      },
+    });
-    );
 
     // We only enable these warnings for the client compiler
     // This avoids emitting duplicate warnings in prod mode

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

@@ -5,15 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import escapeHtml from 'escape-html';
+import type {Node} from 'unist';
-import type {Parent, Node} from 'unist';
+import type {MdxJsxAttributeValueExpression} from 'mdast-util-mdx';
-import type {PhrasingContent, Heading} from 'mdast';
-import type {
-  MdxJsxAttribute,
-  MdxJsxAttributeValueExpression,
-  MdxJsxTextElement,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-} from 'mdast-util-mdx';
 
 /**
  * Util to transform one node type to another node type
@@ -36,70 +29,6 @@ export function transformNode<NewNode extends Node>(
   return node as NewNode;
 }
 
-export function stringifyContent(
-  node: Parent,
-  toString: (param: unknown) => string, // TODO weird but works
-): string {
-  return (node.children as PhrasingContent[])
-    .map((item) => toValue(item, toString))
-    .join('');
-}
-
-// TODO This is really a workaround, and not super reliable
-// For now we only support serializing tagName, className and content
-// Can we implement the TOC with real JSX nodes instead of html strings later?
-function mdxJsxTextElementToHtml(
-  element: MdxJsxTextElement,
-  toString: (param: unknown) => string, // TODO weird but works
-): string {
-  const tag = element.name;
-
-  const attributes = element.attributes.filter(
-    (child): child is MdxJsxAttribute => child.type === 'mdxJsxAttribute',
-  );
-
-  const classAttribute =
-    attributes.find((attr) => attr.name === 'className') ??
-    attributes.find((attr) => attr.name === 'class');
-
-  const classAttributeString = classAttribute
-    ? `class="${escapeHtml(String(classAttribute.value))}"`
-    : ``;
-
-  const allAttributes = classAttributeString ? ` ${classAttributeString}` : '';
-
-  const content = stringifyContent(element, toString);
-
-  return `<${tag}${allAttributes}>${content}</${tag}>`;
-}
-
-export function toValue(
-  node: PhrasingContent | Heading | MdxJsxTextElement,
-  toString: (param: unknown) => string, // TODO weird but works
-): string {
-  switch (node.type) {
-    case 'mdxJsxTextElement': {
-      return mdxJsxTextElementToHtml(node as MdxJsxTextElement, toString);
-    }
-    case 'text':
-      return escapeHtml(node.value);
-    case 'heading':
-      return stringifyContent(node, toString);
-    case 'inlineCode':
-      return `<code>${escapeHtml(node.value)}</code>`;
-    case 'emphasis':
-      return `<em>${stringifyContent(node, toString)}</em>`;
-    case 'strong':
-      return `<strong>${stringifyContent(node, toString)}</strong>`;
-    case 'delete':
-      return `<del>${stringifyContent(node, toString)}</del>`;
-    case 'link':
-      return stringifyContent(node, toString);
-    default:
-      return toString(node);
-  }
-}
-
 export function assetRequireAttributeValue(
   requireString: string,
   hash: string,

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

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

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

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

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

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

packages/docusaurus-plugin-content-blog/assets/atom.xsl

@@ -71,7 +71,7 @@
           <div class="blog-posts">
             <xsl:for-each select="atom:feed/atom:entry">
               <div class="blog-post">
-                <h3><a href="{atom:link[@rel='alternate']/@href}"><xsl:value-of
+                <h3><a href="{atom:link/@href}"><xsl:value-of
                       select="atom:title"
                     /></a></h3>
                 <div class="blog-post-date">

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

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

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/atom.xsl

@@ -71,7 +71,7 @@
           <div class="blog-posts">
             <xsl:for-each select="atom:feed/atom:entry">
               <div class="blog-post">
-                <h3><a href="{atom:link[@rel='alternate']/@href}"><xsl:value-of
+                <h3><a href="{atom:link/@href}"><xsl:value-of
                       select="atom:title"
                     /></a></h3>
                 <div class="blog-post-date">

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/global-tag-permalink (en)/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en" dir="ltr" class="plugin-native plugin-id-default" data-has-hydrated="false">
+<head>
+<meta charset="UTF-8">
+<meta name="generator" content="Docusaurus v3.7.0">
+<title data-rh="true">Page Not Found | Docusaurus blog website fixture</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg"><meta data-rh="true" name="twitter:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg"><meta data-rh="true" property="og:url" content="https://docusaurus.io/blog/tags/global-tag-permalink (en)"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_tag" content="default"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:docusaurus_tag" content="default"><meta data-rh="true" property="og:title" content="Page Not Found | Docusaurus blog website fixture"><link data-rh="true" rel="icon" href="/img/docusaurus.ico"><link data-rh="true" rel="canonical" href="https://docusaurus.io/blog/tags/global-tag-permalink (en)"><link data-rh="true" rel="alternate" href="https://docusaurus.io/blog/tags/global-tag-permalink (en)" hreflang="en"><link data-rh="true" rel="alternate" href="https://docusaurus.io/blog/tags/global-tag-permalink (en)" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://X1Z85QJPUV-dsn.algolia.net" crossorigin="anonymous"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Docusaurus blog website fixture RSS Feed">
+<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Docusaurus blog website fixture Atom Feed">
+<link rel="alternate" type="application/json" href="/blog/feed.json" title="Docusaurus blog website fixture JSON Feed">
+
+
+
+
+<link rel="search" type="application/opensearchdescription+xml" title="Docusaurus blog website fixture" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.5eca0ed4.css">
+<script src="/assets/js/runtime~main.972f9f8c.js" defer="defer"></script>
+<script src="/assets/js/main.52184938.js" defer="defer"></script>
+</head>
+<body class="navigation-with-keyboard">
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;"><defs>
+<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
+</defs></svg>
+<script>!function(){var t="light";var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",e||t),document.documentElement.setAttribute("data-theme-choice",e||t)}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_c5VT" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top navbarHideable_gzXY"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/docusaurus.svg" alt="Docusaurus Logo" class="themedComponent_NoEC themedComponent--light_xEpK"><img src="/img/docusaurus_keytar.svg" alt="Docusaurus Logo" class="themedComponent_NoEC themedComponent--dark__8yu"></div><b class="navbar__title text--truncate">Docusaurus</b></a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="toggle_vYTj colorModeToggle_XGli"><button class="clean-btn toggleButton_dQHP toggleButtonDisabled_T3qH" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_dOhG lightToggleIcon_VoLy"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_dOhG darkToggleIcon_Y09b"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_dOhG systemToggleIcon_hBI2"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_J_Aa"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search (Command+K)"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_cF7l"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div></div>
+</body>
+</html>

packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap

@@ -237,6 +237,10 @@ exports[`atom has custom xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -273,6 +277,10 @@ exports[`atom has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"
@@ -683,6 +691,10 @@ exports[`atom has xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -719,6 +731,10 @@ exports[`atom has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"
@@ -900,6 +916,10 @@ exports[`json has custom xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -936,6 +956,10 @@ exports[`json has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"
@@ -1253,6 +1277,10 @@ exports[`json has xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -1289,6 +1317,10 @@ exports[`json has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"
@@ -1527,6 +1559,10 @@ exports[`rss has custom xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -1563,6 +1599,10 @@ exports[`rss has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"
@@ -1949,6 +1989,10 @@ exports[`rss has xslt files for feed: blog tree 1`] = `
 ├── atom.css
 ├── atom.xml
 ├── atom.xsl
+├── authors
+│   ├── index.html
+│   └── slorber-custom-permalink-localized
+│       └── index.html
 ├── blog-with-links
 │   └── index.html
 ├── custom-atom.css
@@ -1985,6 +2029,10 @@ exports[`rss has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
 │       └── index.html
 └── unlisted
     └── index.html"

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

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

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

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

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * 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 {calculateReadingTime} from '../readingTime';
+
+describe('calculateReadingTime', () => {
+  it('calculates reading time for empty content', () => {
+    expect(calculateReadingTime('')).toBe(0);
+  });
+
+  it('calculates reading time for short content', () => {
+    const content = 'This is a short test content.';
+    expect(calculateReadingTime(content)).toBe(0.03);
+  });
+
+  it('calculates reading time for long content', () => {
+    const content = 'This is a test content. '.repeat(100);
+    expect(calculateReadingTime(content)).toBe(2.5);
+  });
+
+  it('respects custom words per minute', () => {
+    const content = 'This is a test content. '.repeat(100);
+    expect(calculateReadingTime(content, {wordsPerMinute: 100})).toBe(5);
+  });
+
+  it('handles content with special characters', () => {
+    const content = 'Hello! How are you? This is a test...';
+    expect(calculateReadingTime(content)).toBe(0.04);
+  });
+
+  it('handles content with multiple lines', () => {
+    const content = `This is line 1.
+    This is line 2.
+    This is line 3.`;
+    expect(calculateReadingTime(content)).toBe(0.06);
+  });
+
+  it('handles content with HTML tags', () => {
+    const content = '<p>This is a <strong>test</strong> content.</p>';
+    expect(calculateReadingTime(content)).toBe(0.025);
+  });
+
+  it('handles content with markdown', () => {
+    const content = '# Title\n\nThis is **bold** and *italic* text.';
+    expect(calculateReadingTime(content)).toBe(0.04);
+  });
+
+  it('handles CJK content', () => {
+    const content = '你好，世界！这是一段测试内容。';
+    expect(calculateReadingTime(content)).toBe(0.06);
+  });
+});