fix(bundler): fix docusaurus start using concatenateModules: true (#11222)

Co-authored-by: slorber <749374+slorber@users.noreply.github.com>

.cspell.json

@@ -21,7 +21,9 @@
   ],
   "ignorePaths": [
     "CHANGELOG.md",
+    "patches",
     "packages/docusaurus-theme-translations/locales",
+    "packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy",
     "package.json",
     "yarn.lock",
     "project-words.txt",

.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,

.github/workflows/argos.yml

@@ -30,9 +30,10 @@ 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/*
+          cache: yarn
 
       - name: Install dependencies
         run: yarn || yarn || yarn

.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@3b139cfc5fae8b618d3eae3675e383bb1769c019 # 4.5.0
+        uses: actions/dependency-review-action@da24556b548a50705dd671f47852072ea4c105d9 # 4.7.1

.github/workflows/lighthouse-report.yml

@@ -24,9 +24,10 @@ 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/*
+          cache: yarn
 
       - name: Install dependencies
         run: yarn || yarn || yarn
@@ -64,7 +65,7 @@ jobs:
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # 2.9.0
+        uses: marocchino/sticky-pull-request-comment@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

.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

@@ -38,12 +38,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['18.0', '20', '22', '24']
     steps:
       - 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

@@ -27,16 +27,17 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['18.0', '20', '22', '24']
     steps:
       - name: Support longpaths
         run: git config --system core.longpaths true
       - 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
       - name: Installation
         run: yarn || yarn || yarn
       - name: Docusaurus Jest Tests

.github/workflows/tests.yml

@@ -27,12 +27,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22']
+        node: ['18.0', '20', '22', '24']
     steps:
       - 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

.gitignore

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

.nvmrc

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

CHANGELOG.md

@@ -1,5 +1,318 @@
 # Docusaurus Changelog
 
+## 3.8.0 (2025-05-26)
+
+#### :rocket: New Feature
+
+- `docusaurus-plugin-css-cascade-layers`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus`
+  - [#11142](https://github.com/facebook/docusaurus/pull/11142) feat(theme): new CSS cascade layers plugin + built-in `v4.useCssCascadeLayers` future flag ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#11156](https://github.com/facebook/docusaurus/pull/11156) feat(core): add internal flag to skip bundling ([@slorber](https://github.com/slorber))
+  - [#11067](https://github.com/facebook/docusaurus/pull/11067) feat(core): enable Rspack `parallelCodeSplitting` ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`, `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus`
+  - [#11090](https://github.com/facebook/docusaurus/pull/11090) feat(theme): make it possible to provide your own page title formatter ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-pages`
+  - [#11088](https://github.com/facebook/docusaurus/pull/11088) feat(pages): Support `frontMatter.slug` like docs and blog plugins ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`, `docusaurus`
+  - [#11006](https://github.com/facebook/docusaurus/pull/11006) feat(core): Add bundler tracing/profiling ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`
+  - [#10987](https://github.com/facebook/docusaurus/pull/10987) feat(theme): Allow resetting colorMode to System/OS value ([@slorber](https://github.com/slorber))
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#10953](https://github.com/facebook/docusaurus/pull/10953) feat(plugin-npm2yarn): Add Bun to default tabs conversions ([@jakeboone02](https://github.com/jakeboone02))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#10945](https://github.com/facebook/docusaurus/pull/10945) feat(theme): add theme layout stable CSS classes ([@slorber](https://github.com/slorber))
+  - [#10846](https://github.com/facebook/docusaurus/pull/10846) feat(theme): code block showLineNumbers=start metastring ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`, `docusaurus-plugin-content-docs`, `docusaurus-types`, `docusaurus`
+  - [#10931](https://github.com/facebook/docusaurus/pull/10931) feat(core): Docusaurus Faster - Rspack Persistent Cache ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#10852](https://github.com/facebook/docusaurus/pull/10852) feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item ([@hrumhurum](https://github.com/hrumhurum))
+- `docusaurus-types`, `docusaurus`
+  - [#10826](https://github.com/facebook/docusaurus/pull/10826) feat(core): Docusaurus Faster - SSG worker threads ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-sitemap`, `docusaurus-types`, `docusaurus`
+  - [#10850](https://github.com/facebook/docusaurus/pull/10850) feat(core): new `postBuild({routesBuildMetadata})` API, deprecate `head` attribute + v4 future flag ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-plugin-content-blog`
+  - [#11138](https://github.com/facebook/docusaurus/pull/11138) refactor(content-blog): replace `reading-time` with `Intl.Segmenter` API ([@shreedharbhat98](https://github.com/shreedharbhat98))
+- `docusaurus-plugin-content-blog`
+  - [#11138](https://github.com/facebook/docusaurus/pull/11138) refactor(content-blog): replace `reading-time` with `Intl.Segmenter` API ([@shreedharbhat98](https://github.com/shreedharbhat98))
+  - [#11068](https://github.com/facebook/docusaurus/pull/11068) fix(blog): fix blog Atom feed item url / XSL bug ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-docs`
+  - [#11179](https://github.com/facebook/docusaurus/pull/11179) fix(mdx-loader): remove opt-in for mdx dependency file ([@slorber](https://github.com/slorber))
+  - [#10875](https://github.com/facebook/docusaurus/pull/10875) fix(docs): versioning CLI should copy localized translation file `current.json` to `version-<v>.json` ([@jkboxomine](https://github.com/jkboxomine))
+- `create-docusaurus`
+  - [#11157](https://github.com/facebook/docusaurus/pull/11157) fix(create-docusaurus): Improve init template README, fix headings and remove $ in bash code blocks ([@arienshibani](https://github.com/arienshibani))
+- `docusaurus-theme-common`
+  - [#11153](https://github.com/facebook/docusaurus/pull/11153) fix(theme): restore former code block theme-common internal APIs ([@slorber](https://github.com/slorber))
+  - [#11046](https://github.com/facebook/docusaurus/pull/11046) fix(theme): Fix code block magic comments with CRLF line breaks bug ([@coder-xiaomo](https://github.com/coder-xiaomo))
+  - [#10989](https://github.com/facebook/docusaurus/pull/10989) fix(theme): mobile drawer history blocker should be rendered conditionally (workaround) ([@slorber](https://github.com/slorber))
+  - [#10954](https://github.com/facebook/docusaurus/pull/10954) fix(theme): fix `useColorMode().colorMode` leading to React hydration mismatches ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#11085](https://github.com/facebook/docusaurus/pull/11085) fix(theme): add missing `rel="tag"` attribute for docs/blog tags ([@slorber](https://github.com/slorber))
+  - [#10999](https://github.com/facebook/docusaurus/pull/10999) fix(theme): CodeBlock should accept `title` of `ReactNode` type ([@lebalz](https://github.com/lebalz))
+  - [#10705](https://github.com/facebook/docusaurus/pull/10705) fix(theme): only render secondaryMenu if it should be shown ([@hidde](https://github.com/hidde))
+  - [#10898](https://github.com/facebook/docusaurus/pull/10898) fix(theme): a11y fix on mobile DropdownNavbarItem ([@mxschmitt](https://github.com/mxschmitt))
+  - [#10909](https://github.com/facebook/docusaurus/pull/10909) fix(theme): apply docs `sidebar_class_name` in DocCard + better dogfooding ([@slorber](https://github.com/slorber))
+  - [#10849](https://github.com/facebook/docusaurus/pull/10849) fix(theme): fix `<DocCard>` height inconsistency ([@hichemfantar](https://github.com/hichemfantar))
+  - [#10866](https://github.com/facebook/docusaurus/pull/10866) fix(theme): Hide code block buttons before React hydration ([@kennethormandy](https://github.com/kennethormandy))
+- `docusaurus-theme-classic`, `docusaurus-theme-translations`
+  - [#11053](https://github.com/facebook/docusaurus/pull/11053) fix(theme): navbar mobile sidebar should allow clicking dropdown parent link ([@slorber](https://github.com/slorber))
+- `docusaurus-utils`
+  - [#11027](https://github.com/facebook/docusaurus/pull/11027) fix(cli): fix CLI write-translation bug ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#11030](https://github.com/facebook/docusaurus/pull/11030) fix(theme-translation): add missing Japanese translation for System Mode ([@tats-u](https://github.com/tats-u))
+  - [#10893](https://github.com/facebook/docusaurus/pull/10893) fix(theme-translations): Turkish exist language translate completed. ([@ramazansancar](https://github.com/ramazansancar))
+  - [#10884](https://github.com/facebook/docusaurus/pull/10884) fix(theme-translations): Add missing Polish (pl) theme translations ([@mariuszkrzaczkowski](https://github.com/mariuszkrzaczkowski))
+- `docusaurus-plugin-ideal-image`
+  - [#11026](https://github.com/facebook/docusaurus/pull/11026) fix(ideal-image): fix waypoint initial scroll bug ([@slorber](https://github.com/slorber))
+  - [#11014](https://github.com/facebook/docusaurus/pull/11014) fix(ideal-image): Internalize `react-waypoint` dependency, fix React 19 compatibility ([@slorber](https://github.com/slorber))
+  - [#10910](https://github.com/facebook/docusaurus/pull/10910) fix(ideal-image): Add issuer to ideal-image Webpack loader ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`
+  - [#11004](https://github.com/facebook/docusaurus/pull/11004) fix(mdx-loader): refactor and fix heading to toc html value serialization ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`
+  - [#10998](https://github.com/facebook/docusaurus/pull/10998) fix(module-type-aliases): pin react-helmet-async to @slorber/react-helmet-async@1.3.0 ([@cylewaitforit](https://github.com/cylewaitforit))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`
+  - [#10987](https://github.com/facebook/docusaurus/pull/10987) feat(theme): Allow resetting colorMode to System/OS value ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-utils`
+  - [#10958](https://github.com/facebook/docusaurus/pull/10958) fix(create-docusaurus): fix CLI and remove shelljs escapeShellArg util ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`
+  - [#10934](https://github.com/facebook/docusaurus/pull/10934) fix(docs): fix mdx loader cache invalidation bug on versions changes ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`
+  - [#10929](https://github.com/facebook/docusaurus/pull/10929) fix(plugins): add missing `validateOptions` types ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#10888](https://github.com/facebook/docusaurus/pull/10888) fix(seo): docs breadcrumb structured data should use JSON-LD and filter unliked categories ([@johnnyreilly](https://github.com/johnnyreilly))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#10886](https://github.com/facebook/docusaurus/pull/10886) fix(theme): collapse doc sidebar category on label click if active ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10915](https://github.com/facebook/docusaurus/pull/10915) fix(core): use `os.availableParallelism()` for SSG worker threads count ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`
+  - [#10847](https://github.com/facebook/docusaurus/pull/10847) fix(theme): Fix `<DocCardList>` usage on docs at root of a sidebar ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-svgr`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#10820](https://github.com/facebook/docusaurus/pull/10820) fix(core): restore core svg file-loader ([@slorber](https://github.com/slorber))
+- `docusaurus-logger`
+  - [#10818](https://github.com/facebook/docusaurus/pull/10818) fix: perflogger mark detail bug ([@slorber](https://github.com/slorber))
+
+#### :running_woman: Performance
+
+- `docusaurus-utils`, `docusaurus`
+  - [#11178](https://github.com/facebook/docusaurus/pull/11178) perf(core): disable Rspack `parallelCodeSplitting` temporarily ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#11177](https://github.com/facebook/docusaurus/pull/11177) perf(core): fix bad value for mergeDuplicateChunks (typo) ([@slorber](https://github.com/slorber))
+  - [#11170](https://github.com/facebook/docusaurus/pull/11170) perf(core): add default for DOCUSAURUS_SSG_WORKER_THREAD_RECYCLER_MAX_MEMORY ([@slorber](https://github.com/slorber))
+  - [#11166](https://github.com/facebook/docusaurus/pull/11166) feat(core): expose opt-in env variable for SSG thread recycling ([@slorber](https://github.com/slorber))
+  - [#11072](https://github.com/facebook/docusaurus/pull/11072) perf(core): remove bundler `optimization.removeAvailableModules` ([@slorber](https://github.com/slorber))
+  - [#11067](https://github.com/facebook/docusaurus/pull/11067) feat(core): enable Rspack `parallelCodeSplitting` ([@slorber](https://github.com/slorber))
+  - [#11037](https://github.com/facebook/docusaurus/pull/11037) refactor(core): remove clean-webpack-plugin ([@slorber](https://github.com/slorber))
+  - [#11007](https://github.com/facebook/docusaurus/pull/11007) perf(core): Optimize `docusaurus start/serve`, fix `openBrowser()` perf issue on macOS ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`, `docusaurus`
+  - [#11176](https://github.com/facebook/docusaurus/pull/11176) perf(bundler): fine-tuning of Webpack/Rspack optimizations ([@slorber](https://github.com/slorber))
+- `docusaurus-utils`
+  - [#11163](https://github.com/facebook/docusaurus/pull/11163) perf(utils): implement git command queue ([@slorber](https://github.com/slorber))
+- `docusaurus-logger`, `docusaurus`
+  - [#11162](https://github.com/facebook/docusaurus/pull/11162) perf(core): optimize SSG collected data memory and worker thread communication ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus`
+  - [#10956](https://github.com/facebook/docusaurus/pull/10956) refactor: remove `react-dev-utils` (CRA) dependency, internalize code ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#10885](https://github.com/facebook/docusaurus/pull/10885) perf(theme): use SVG sprite for IconExternalLink ([@slorber](https://github.com/slorber))
+- `docusaurus-types`, `docusaurus`
+  - [#10826](https://github.com/facebook/docusaurus/pull/10826) feat(core): Docusaurus Faster - SSG worker threads ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-live-codeblock`
+  - [#11120](https://github.com/facebook/docusaurus/pull/11120) fix(theme): improve color contrast of live code block header ([@JackHowa](https://github.com/JackHowa))
+- `docusaurus-theme-translations`
+  - [#10825](https://github.com/facebook/docusaurus/pull/10825) fix(theme-translations): Add missing Polish (pl) theme translations ([@mariuszkrzaczkowski](https://github.com/mariuszkrzaczkowski))
+  - [#10816](https://github.com/facebook/docusaurus/pull/10816) chore(theme-translations): add missing zh theme translations ([@MisterFISHUP](https://github.com/MisterFISHUP))
+
+#### :memo: Documentation
+
+- [#11181](https://github.com/facebook/docusaurus/pull/11181) docs: adjust the Docusaurus release process documentation to our new simpler process ([@slorber](https://github.com/slorber))
+- [#11180](https://github.com/facebook/docusaurus/pull/11180) docs(ideal-image): Add warning for pnpm 10+ and `sharp` install script ([@slorber](https://github.com/slorber))
+- [#11137](https://github.com/facebook/docusaurus/pull/11137) docs(deploy): remove `layer0` from deployment docs ([@PaiJi](https://github.com/PaiJi))
+- [#10822](https://github.com/facebook/docusaurus/pull/10822) docs(website): Comparison with Rspress ([@DevJoaoLopes](https://github.com/DevJoaoLopes))
+
+#### :robot: Dependencies
+
+- [#11185](https://github.com/facebook/docusaurus/pull/11185) chore(deps): bump actions/dependency-review-action from 4.7.0 to 4.7.1 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11182](https://github.com/facebook/docusaurus/pull/11182) chore(deps): bump lockfile-lint-api from 5.9.1 to 5.9.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11174](https://github.com/facebook/docusaurus/pull/11174) chore(deps): bump actions/dependency-review-action from 4.6.0 to 4.7.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11135](https://github.com/facebook/docusaurus/pull/11135) chore(deps): bump http-proxy-middleware from 2.0.7 to 2.0.9 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11103](https://github.com/facebook/docusaurus/pull/11103) chore(deps): bump marocchino/sticky-pull-request-comment from 2.9.1 to 2.9.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11102](https://github.com/facebook/docusaurus/pull/11102) chore(deps): bump actions/setup-node from 4.3.0 to 4.4.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11070](https://github.com/facebook/docusaurus/pull/11070) chore(deps): bump estree-util-value-to-estree from 3.1.2 to 3.3.3 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11069](https://github.com/facebook/docusaurus/pull/11069) chore(deps): bump actions/dependency-review-action from 4.5.0 to 4.6.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11002](https://github.com/facebook/docusaurus/pull/11002) chore(deps): bump actions/setup-node from 4.2.0 to 4.3.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10990](https://github.com/facebook/docusaurus/pull/10990) chore(deps): bump @babel/runtime-corejs3 from 7.25.9 to 7.26.10 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10970](https://github.com/facebook/docusaurus/pull/10970) chore(deps): bump axios from 1.7.7 to 1.8.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10978](https://github.com/facebook/docusaurus/pull/10978) chore(deps): bump prismjs from 1.29.0 to 1.30.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10957](https://github.com/facebook/docusaurus/pull/10957) chore(deps): bump http-proxy-middleware from 2.0.6 to 2.0.7 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10937](https://github.com/facebook/docusaurus/pull/10937) chore(deps): bump dompurify from 3.1.6 to 3.2.4 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10936](https://github.com/facebook/docusaurus/pull/10936) chore(deps): bump preactjs/compressed-size-action from 2.7.0 to 2.8.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10873](https://github.com/facebook/docusaurus/pull/10873) chore(deps): bump actions/setup-node from 4.1.0 to 4.2.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10853](https://github.com/facebook/docusaurus/pull/10853) chore(deps): bump marocchino/sticky-pull-request-comment from 2.9.0 to 2.9.1 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10851](https://github.com/facebook/docusaurus/pull/10851) chore(deps): bump katex from 0.16.11 to 0.16.21 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :wrench: Maintenance
+
+- `docusaurus-mdx-loader`, `docusaurus-utils`
+  - [#11168](https://github.com/facebook/docusaurus/pull/11168) chore: add Node 24 to CI + fix deprecation warnings ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`
+  - [#11116](https://github.com/facebook/docusaurus/pull/11116) test(blog): Add unit tests for calculating blog posts reading time ([@shreedharbhat98](https://github.com/shreedharbhat98))
+- `docusaurus-mdx-loader`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`
+  - [#11077](https://github.com/facebook/docusaurus/pull/11077) refactor(live-codeblock): refactor live code block theme components ([@slorber](https://github.com/slorber))
+- Other
+  - [#11075](https://github.com/facebook/docusaurus/pull/11075) fix(c): fix `yarn lint:spelling:fix` script ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`
+  - [#11073](https://github.com/facebook/docusaurus/pull/11073) chore: upgrade Rspack 1.3.3 ([@slorber](https://github.com/slorber))
+  - [#10870](https://github.com/facebook/docusaurus/pull/10870) chore(deps): bump @rspack/core in Faster from 1.2.0-alpha.0 to 1.2.2 ([@tats-u](https://github.com/tats-u))
+- `docusaurus-theme-mermaid`
+  - [#11066](https://github.com/facebook/docusaurus/pull/11066) chore: upgrade mermaid, fix diagram labels bug ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`
+  - [#11065](https://github.com/facebook/docusaurus/pull/11065) chore: upgrade image-size deps to v2 ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#11062](https://github.com/facebook/docusaurus/pull/11062) refactor(theme): introduce CodeBlockContextProvider + split into smaller components ([@slorber](https://github.com/slorber))
+  - [#11059](https://github.com/facebook/docusaurus/pull/11059) refactor(theme): CodeBlock, centralize metadata parsing + refactor theme component ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-common`
+  - [#11058](https://github.com/facebook/docusaurus/pull/11058) refactor(theme): refactor CodeBlock parseLines logic + use inline snapshots to ease review ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`, `docusaurus`
+  - [#11039](https://github.com/facebook/docusaurus/pull/11039) chore: use rspack 1.3.0 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-ideal-image`
+  - [#11010](https://github.com/facebook/docusaurus/pull/11010) refactor(ideal-image-plugin): internalize legacy component code ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-mermaid`, `docusaurus-theme-search-algolia`
+  - [#10969](https://github.com/facebook/docusaurus/pull/10969) chore: add `eslint-plugin-react-compiler` ([@slorber](https://github.com/slorber))
+- `docusaurus-cssnano-preset`, `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-remark-plugin-npm2yarn`, `eslint-plugin`, `stylelint-copyright`
+  - [#10966](https://github.com/facebook/docusaurus/pull/10966) chore: upgrade monorepo to TS 5.8 ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus`
+  - [#10956](https://github.com/facebook/docusaurus/pull/10956) refactor: remove `react-dev-utils` (CRA) dependency, internalize code ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-plugin-content-docs`, `docusaurus-utils`, `docusaurus`
+  - [#10358](https://github.com/facebook/docusaurus/pull/10358) refactor: replace unmaintained shelljs dependency by execa ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-theme-search-algolia`
+  - [#10941](https://github.com/facebook/docusaurus/pull/10941) chore(algolia): bump docsearch dependency to v3.9 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-debug`
+  - [#10903](https://github.com/facebook/docusaurus/pull/10903) chore(plugin-debug): upgrade react-json-view-lite to v2.3.0 for react 19 ([@reece-white](https://github.com/reece-white))
+  - [#10819](https://github.com/facebook/docusaurus/pull/10819) chore(plugin-debug): upgrade react-json-view-lite to v2, prepare for React 19 ([@slorber](https://github.com/slorber))
+- `create-docusaurus`
+  - [#10871](https://github.com/facebook/docusaurus/pull/10871) refactor(create-docusaurus): add `future.v4` flag to init templates ([@slorber](https://github.com/slorber))
+
+#### Committers: 38
+
+- Arien Shibani ([@arienshibani](https://github.com/arienshibani))
+- Balthasar Hofer ([@lebalz](https://github.com/lebalz))
+- Ben McCann ([@benmccann](https://github.com/benmccann))
+- Daniel Kuschny ([@Danielku15](https://github.com/Danielku15))
+- David King Roderos ([@dkroderos](https://github.com/dkroderos))
+- FISH UP ([@MisterFISHUP](https://github.com/MisterFISHUP))
+- Hichem Fantar ([@hichemfantar](https://github.com/hichemfantar))
+- Hidde de Vries ([@hidde](https://github.com/hidde))
+- Jack Howard ([@JackHowa](https://github.com/JackHowa))
+- Jake Boone ([@jakeboone02](https://github.com/jakeboone02))
+- JiPai ([@PaiJi](https://github.com/PaiJi))
+- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- João Victor Lopes ([@DevJoaoLopes](https://github.com/DevJoaoLopes))
+- Justin D Mathew ([@JDMathew](https://github.com/JDMathew))
+- Kenneth Ormandy ([@kennethormandy](https://github.com/kennethormandy))
+- Mariusz Krzaczkowski ([@mariuszkrzaczkowski](https://github.com/mariuszkrzaczkowski))
+- Massoud Maboudi ([@massoudmaboudi](https://github.com/massoudmaboudi))
+- Max Schmitt ([@mxschmitt](https://github.com/mxschmitt))
+- Milica ([@mmaksimovic](https://github.com/mmaksimovic))
+- Oleksiy Gapotchenko ([@hrumhurum](https://github.com/hrumhurum))
+- Ramazan Sancar ([@ramazansancar](https://github.com/ramazansancar))
+- Shreedhar Bhat ([@shreedharbhat98](https://github.com/shreedharbhat98))
+- Stephen Glass ([@stephenglass](https://github.com/stephenglass))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Taras ([@taraspos](https://github.com/taraspos))
+- Tatsunori Uchino ([@tats-u](https://github.com/tats-u))
+- Waldir Pimenta ([@waldyrious](https://github.com/waldyrious))
+- Yangshun Tay ([@yangshun](https://github.com/yangshun))
+- Yoshiaki Yoshida ([@kakakakakku](https://github.com/kakakakakku))
+- [@cylewaitforit](https://github.com/cylewaitforit)
+- [@jkboxomine](https://github.com/jkboxomine)
+- [@reece-white](https://github.com/reece-white)
+- kilavvy ([@kilavvy](https://github.com/kilavvy))
+- ozaki ([@OzakIOne](https://github.com/OzakIOne))
+- pedenys ([@pedenys](https://github.com/pedenys))
+- マルコメ ([@Marukome0743](https://github.com/Marukome0743))
+- 程序员小墨 ([@coder-xiaomo](https://github.com/coder-xiaomo))
+
+## 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

admin/new.docusaurus.io/package.json

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

admin/publish.md

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

admin/scripts/resizeImage.js

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

admin/test-bad-package/package.json

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

argos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argos",
-  "version": "3.6.3",
+  "version": "3.8.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

examples/README.md

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

examples/classic-typescript/README.md

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

examples/classic-typescript/blog/authors.yml

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

examples/classic-typescript/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

examples/classic-typescript/package.json

@@ -16,18 +16,18 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.0",
-    "@docusaurus/preset-classic": "3.6.0",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/preset-classic": "3.8.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.0",
-    "@docusaurus/tsconfig": "3.6.0",
-    "@docusaurus/types": "3.6.0",
+    "@docusaurus/module-type-aliases": "3.8.0",
+    "@docusaurus/tsconfig": "3.8.0",
+    "@docusaurus/types": "3.8.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

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

examples/classic/blog/authors.yml

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

examples/classic/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

examples/classic/package.json

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

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.3",
+  "version": "3.8.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",
@@ -29,8 +31,9 @@
     "build:website:deployPreview": "yarn build:website:deployPreview:testWrap && yarn build:website:deployPreview:build",
     "build:website:fast": "yarn workspace website build:fast",
     "build:website:fast:rsdoctor": "yarn workspace website build:fast:rsdoctor",
-    "build:website:fast:profile": "yarn workspace website build:fast:profile",
     "build:website:en": "yarn workspace website build --locale en",
+    "profile:bundle:cpu": "yarn workspace website profile:bundle:cpu:profile",
+    "profile:bundle:samply": "yarn workspace website profile:bundle:samply",
     "clear:website": "yarn workspace website clear",
     "serve:website": "yarn workspace website serve",
     "serve:website:baseUrl": "serve website",
@@ -50,7 +53,7 @@
     "canary:bumpVersion": "yarn lerna version `yarn --silent canary:version` --exact --no-push --yes",
     "canary:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "changelog": "lerna-changelog",
-    "postinstall": "yarn lock:update && yarn build:packages",
+    "postinstall": "patch-package && yarn lock:update && yarn build:packages",
     "prepare": "husky install",
     "format": "prettier --write .",
     "format:diff": "prettier --list-different .",
@@ -59,7 +62,7 @@
     "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
     "lint:js:fix": "yarn lint:js --fix",
     "lint:spelling": "cspell \"**\" --no-progress --show-context --show-suggestions",
-    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=en_US.UTF-8 sort --ignore-case >> project-words.txt",
+    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=C sort --ignore-case >> project-words.txt",
     "lint:style": "stylelint \"**/*.css\"",
     "lint:style:fix": "yarn lint:style --fix",
     "lerna": "lerna",
@@ -83,14 +86,13 @@
     "@types/node": "^18.16.19",
     "@types/prompts": "^2.4.4",
     "@types/react": "^18.2.15",
-    "@types/react-dev-utils": "^9.0.11",
     "@types/react-test-renderer": "^18.0.0",
     "@types/semver": "^7.5.0",
     "@types/shelljs": "^0.8.12",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
-    "cspell": "^8.1.0",
+    "cspell": "^8.18.1",
     "eslint": "^8.45.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^8.8.0",
@@ -99,10 +101,11 @@
     "eslint-plugin-jest": "^27.2.3",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-compiler": "^19.0.0-beta-40c6c23-20250301",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-regexp": "^1.15.0",
     "husky": "^8.0.3",
-    "image-size": "^1.0.2",
+    "image-size": "^2.0.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-serializer-ansi-escapes": "^3.0.0",
@@ -112,6 +115,8 @@
     "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",
@@ -122,7 +127,7 @@
     "stylelint": "^14.16.1",
     "stylelint-config-prettier": "^9.0.5",
     "stylelint-config-standard": "^29.0.0",
-    "typescript": "~5.7.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.3",
+  "version": "3.8.0",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,14 +22,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.6.3",
-    "@docusaurus/utils": "3.6.3",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/utils": "3.8.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 hasPnpm = shell.exec('pnpm --version', {silent: true}).code === 0;
-  const hasBun = shell.exec('bun --version', {silent: true}).code === 0;
+  const hasYarn = (await execa.command('yarn --version')).exitCode === 0;
+  const hasPnpm = (await execa.command('pnpm --version')).exitCode === 0;
+  const hasBun = (await execa.command('bun --version')).exitCode === 0;
 
   if (!hasYarn && !hasPnpm && !hasBun) {
     return 'npm';
@@ -530,10 +533,7 @@ export default async function init(
 
   if (source.type === 'git') {
     const gitCommand = await getGitCommand(source.strategy);
-    const gitCloneCommand = `${gitCommand} ${escapeShellArg(
-      source.url,
-    )} ${escapeShellArg(dest)}`;
-    if (shell.exec(gitCloneCommand).code !== 0) {
+    if ((await execa(gitCommand, [source.url, dest])).exitCode !== 0) {
       logger.error`Cloning Git template failed!`;
       process.exit(1);
     }
@@ -583,24 +583,27 @@ export default async function init(
   const cdpath = path.relative('.', dest);
   const pkgManager = await getPackageManager(dest, cliOptions);
   if (!cliOptions.skipInstall) {
-    shell.cd(dest);
+    process.chdir(dest);
     logger.info`Installing dependencies with name=${pkgManager}...`;
+    // ...
+
     if (
-      shell.exec(
-        pkgManager === 'yarn'
-          ? 'yarn'
-          : pkgManager === 'bun'
-          ? 'bun install'
-          : `${pkgManager} install --color always`,
-        {
-          env: {
-            ...process.env,
-            // Force coloring the output, since the command is invoked by
-            // shelljs, which is not an interactive shell
-            ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+      (
+        await execa.command(
+          pkgManager === 'yarn'
+            ? 'yarn'
+            : pkgManager === 'bun'
+            ? 'bun install'
+            : `${pkgManager} install --color always`,
+          {
+            env: {
+              ...process.env,
+              // Force coloring the output
+              ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+            },
           },
-        },
-      ).code !== 0
+        )
+      ).exitCode !== 0
     ) {
       logger.error('Dependency installation failed.');
       logger.info`The site directory has already been created, and you can retry by typing:

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

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

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

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

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.3",
+  "version": "3.8.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,8 +14,8 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "3.6.3",
-    "@docusaurus/preset-classic": "3.6.3",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/preset-classic": "3.8.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
@@ -23,8 +23,8 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.6.3",
-    "@docusaurus/types": "3.6.3"
+    "@docusaurus/module-type-aliases": "3.8.0",
+    "@docusaurus/types": "3.8.0"
   },
   "browserslist": {
     "production": [

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

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

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

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

packages/docusaurus-babel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/babel",
-  "version": "3.6.3",
+  "version": "3.8.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.3",
-    "@docusaurus/utils": "3.6.3",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/utils": "3.8.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.3",
+  "version": "3.8.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.3",
-    "@docusaurus/cssnano-preset": "3.6.3",
-    "@docusaurus/logger": "3.6.3",
-    "@docusaurus/types": "3.6.3",
-    "@docusaurus/utils": "3.6.3",
+    "@docusaurus/babel": "3.8.0",
+    "@docusaurus/cssnano-preset": "3.8.0",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/types": "3.8.0",
+    "@docusaurus/utils": "3.8.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/currentBundler.ts

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

packages/docusaurus-bundler/src/index.ts

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

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

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

packages/docusaurus-cssnano-preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/cssnano-preset",
-  "version": "3.6.3",
+  "version": "3.8.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.3",
+  "version": "3.8.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.3",
-    "@rspack/core": "1.2.0-alpha.0",
+    "@docusaurus/types": "3.8.0",
+    "@rspack/core": "^1.3.10",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",

packages/docusaurus-logger/package.json

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

packages/docusaurus-logger/src/perfLogger.ts

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

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "3.6.3",
+  "version": "3.8.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.3",
-    "@docusaurus/utils": "3.6.3",
-    "@docusaurus/utils-validation": "3.6.3",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/utils": "3.8.0",
+    "@docusaurus/utils-validation": "3.8.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.3",
+    "@docusaurus/types": "3.8.0",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",

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

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 type {Node} from 'unist';
+import escapeHtml from 'escape-html';
+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/index.ts

@@ -8,21 +8,19 @@
 import path from 'path';
 import url from 'url';
 import fs from 'fs-extra';
-import {promisify} from 'util';
 import {
   toMessageRelativeFilePath,
   posixPath,
   escapePath,
   findAsyncSequential,
   getFileLoaderUtils,
+  parseURLOrPath,
 } 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';
@@ -53,7 +51,7 @@ async function toImageRequireNode(
   );
   relativeImagePath = `./${relativeImagePath}`;
 
-  const parsedUrl = url.parse(node.url);
+  const parsedUrl = parseURLOrPath(node.url, 'https://example.com');
   const hash = parsedUrl.hash ?? '';
   const search = parsedUrl.search ?? '';
   const requireString = `${context.inlineMarkdownImageFileLoader}${
@@ -82,7 +80,7 @@ async function toImageRequireNode(
   }
 
   try {
-    const size = (await promisify(sizeOf)(imagePath))!;
+    const size = (await imageSizeFromFile(imagePath))!;
     if (size.width) {
       attributes.push({
         type: 'mdxJsxAttribute',

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

@@ -14,12 +14,11 @@ import {
   escapePath,
   findAsyncSequential,
   getFileLoaderUtils,
+  parseURLOrPath,
 } 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';
@@ -53,7 +52,7 @@ async function toAssetRequireNode(
     path.relative(path.dirname(context.filePath), assetPath),
   )}`;
 
-  const parsedUrl = url.parse(node.url);
+  const parsedUrl = parseURLOrPath(node.url);
   const hash = parsedUrl.hash ?? '';
   const search = parsedUrl.search ?? '';
 

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';
-
-// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-import type {Transformer, Processor, Parent, Plugin} from 'unified';
-import type {
-  Directives,
-  TextDirective,
-  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
-} from 'mdast-util-directive';
+import type {Parent} from 'unist';
+import type {Transformer, Processor, Plugin} from 'unified';
+import type {Directives, TextDirective} from 'mdast-util-directive';
 
 type DirectiveType = Directives['type'];
 
@@ -133,21 +128,18 @@ const plugin: Plugin<unknown[], Root> = function plugin(
 
     const unusedDirectives: Directives[] = [];
 
-    visit<Parent, DirectiveType[]>(
-      tree,
-      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)) {
-          if (isSimpleTextDirective(directive)) {
-            transformSimpleTextDirectiveToString(directive);
-          } else {
-            unusedDirectives.push(directive);
-          }
+    // @ts-expect-error: TODO fix type
+    visit<Parent, Directives>(tree, 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)) {
+        if (isSimpleTextDirective(directive)) {
+          transformSimpleTextDirectiveToString(directive);
+        } else {
+          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 {Parent, Node} from 'unist';
-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';
+import type {Node} from 'unist';
+import type {MdxJsxAttributeValueExpression} 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.3",
+  "version": "3.8.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.3",
+    "@docusaurus/types": "3.8.0",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",
     "@types/react-router-dom": "*",
-    "react-helmet-async": "npm:@slorber/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

@@ -122,6 +122,15 @@ declare module '@theme/Root' {
   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' {
   import type {ReactNode} from 'react';
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-client-redirects",
-  "version": "3.6.3",
+  "version": "3.8.0",
   "description": "Client redirects plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,18 +18,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.3",
-    "@docusaurus/logger": "3.6.3",
-    "@docusaurus/utils": "3.6.3",
-    "@docusaurus/utils-common": "3.6.3",
-    "@docusaurus/utils-validation": "3.6.3",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/utils": "3.8.0",
+    "@docusaurus/utils-common": "3.8.0",
+    "@docusaurus/utils-validation": "3.8.0",
     "eta": "^2.2.0",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "tslib": "^2.6.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.6.3"
+    "@docusaurus/types": "3.8.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.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.3",
+  "version": "3.8.0",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,19 +31,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.6.3",
-    "@docusaurus/logger": "3.6.3",
-    "@docusaurus/mdx-loader": "3.6.3",
-    "@docusaurus/theme-common": "3.6.3",
-    "@docusaurus/types": "3.6.3",
-    "@docusaurus/utils": "3.6.3",
-    "@docusaurus/utils-common": "3.6.3",
-    "@docusaurus/utils-validation": "3.6.3",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/logger": "3.8.0",
+    "@docusaurus/mdx-loader": "3.8.0",
+    "@docusaurus/theme-common": "3.8.0",
+    "@docusaurus/types": "3.8.0",
+    "@docusaurus/utils": "3.8.0",
+    "@docusaurus/utils-common": "3.8.0",
+    "@docusaurus/utils-validation": "3.8.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",

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,7 +277,11 @@ exports[`atom has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── 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,7 +731,11 @@ exports[`atom has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── 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,7 +956,11 @@ exports[`json has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── 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,7 +1317,11 @@ exports[`json has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── 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,7 +1599,11 @@ exports[`rss has custom xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── 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,7 +2029,11 @@ exports[`rss has xslt files for feed: blog tree 1`] = `
 │   │   └── index.html
 │   ├── date
 │   │   └── index.html
-│   └── index.html
+│   ├── global-tag-permalink (en)
+│   │   └── index.html
+│   ├── index.html
+│   └── inline-tag
+│       └── index.html
 └── unlisted
     └── index.html"
 `;

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

@@ -150,7 +150,7 @@ exports[`blog plugin process blog posts load content 2`] = `
         "title": "Another With Tag",
       },
       "permalink": "/blog/simple/slug/another",
-      "readingTime": 0.015,
+      "readingTime": 0.02,
       "source": "@site/blog/another-simple-slug-with-tags.md",
       "tags": [
         {

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

@@ -23,7 +23,6 @@ describe('normalizeSocials', () => {
       mastodon: 'Mastodon',
     };
 
-    // eslint-disable-next-line jest/no-large-snapshots
     expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
       {
         "bluesky": "https://bsky.app/profile/gingergeek.co.uk",

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

@@ -120,7 +120,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: {atom: null, rss: null},
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -164,7 +164,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: {atom: null, rss: null},
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -220,7 +220,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: {atom: null, rss: null},
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -267,7 +267,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: {atom: null, rss: null},
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -314,7 +314,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: {atom: null, rss: null},
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -360,7 +360,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           xslt: true,
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',
@@ -409,7 +409,7 @@ describe.each(['atom', 'rss', 'json'] as const)('%s', (feedType) => {
           },
         },
         readingTime: ({content, defaultReadingTime}) =>
-          defaultReadingTime({content}),
+          defaultReadingTime({content, locale: 'en'}),
         truncateMarker: /<!--\s*truncate\s*-->/,
         onInlineTags: 'ignore',
         onInlineAuthors: 'ignore',

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

@@ -211,7 +211,7 @@ describe('blog plugin', () => {
     ).toEqual({
       editUrl: `${BaseEditUrl}/blog/2018-12-14-Happy-First-Birthday-Slash.md`,
       permalink: '/blog/2018/12/14/Happy-First-Birthday-Slash',
-      readingTime: 0.015,
+      readingTime: 0.02,
       source: path.posix.join(
         '@site',
         path.posix.join('i18n', 'en', 'docusaurus-plugin-content-blog'),
@@ -276,7 +276,7 @@ describe('blog plugin', () => {
     }).toEqual({
       editUrl: `${BaseEditUrl}/blog/complex-slug.md`,
       permalink: '/blog/hey/my super path/héllô',
-      readingTime: 0.015,
+      readingTime: 0.02,
       source: path.posix.join('@site', PluginPath, 'complex-slug.md'),
       title: 'Complex Slug',
       description: `complex url slug`,
@@ -318,7 +318,7 @@ describe('blog plugin', () => {
     }).toEqual({
       editUrl: `${BaseEditUrl}/blog/simple-slug.md`,
       permalink: '/blog/simple/slug',
-      readingTime: 0.015,
+      readingTime: 0.02,
       source: path.posix.join('@site', PluginPath, 'simple-slug.md'),
       title: 'Simple Slug',
       description: `simple url slug`,

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

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

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

@@ -9,7 +9,6 @@ import fs from 'fs-extra';
 import path from 'path';
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import readingTime from 'reading-time';
 import {
   parseMarkdownFile,
   normalizeUrl,
@@ -32,6 +31,7 @@ import {getTagsFile} from '@docusaurus/utils-validation';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {getBlogPostAuthors} from './authors';
 import {reportAuthorsProblems} from './authorsProblems';
+import {calculateReadingTime} from './readingTime';
 import type {TagsFile} from '@docusaurus/utils';
 import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
@@ -210,8 +210,8 @@ async function parseBlogPostMarkdownFile({
   }
 }
 
-const defaultReadingTime: ReadingTimeFunction = ({content, options}) =>
-  readingTime(content, options).minutes;
+const defaultReadingTime: ReadingTimeFunction = ({content, locale, options}) =>
+  calculateReadingTime(content, locale, options);
 
 async function processBlogSourceFile(
   blogSourceRelative: string,
@@ -373,6 +373,7 @@ async function processBlogSourceFile(
             content,
             frontMatter,
             defaultReadingTime,
+            locale: i18n.currentLocale,
           })
         : undefined,
       hasTruncateMarker: truncateMarker.test(content),

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

@@ -63,7 +63,8 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   path: 'blog',
   editLocalizedFiles: false,
   authorsMapPath: 'authors.yml',
-  readingTime: ({content, defaultReadingTime}) => defaultReadingTime({content}),
+  readingTime: ({content, defaultReadingTime, locale}) =>
+    defaultReadingTime({content, locale}),
   sortPosts: 'descending',
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,

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

@@ -16,7 +16,12 @@ declare module '@docusaurus/plugin-content-blog' {
     FrontMatterLastUpdate,
     TagsPluginOptions,
   } from '@docusaurus/utils';
-  import type {DocusaurusConfig, Plugin, LoadContext} from '@docusaurus/types';
+  import type {
+    DocusaurusConfig,
+    Plugin,
+    LoadContext,
+    OptionValidationContext,
+  } from '@docusaurus/types';
   import type {Item as FeedItem} from 'feed';
   import type {Overwrite} from 'utility-types';
 
@@ -382,15 +387,10 @@ declare module '@docusaurus/plugin-content-blog' {
   };
 
   /**
-   * Duplicate from ngryman/reading-time to keep stability of API.
+   * Options for reading time calculation using Intl.Segmenter.
    */
   type ReadingTimeOptions = {
     wordsPerMinute?: number;
-    /**
-     * @param char The character to be matched.
-     * @returns `true` if this character is a word bound.
-     */
-    wordBound?: (char: string) => boolean;
   };
 
   /**
@@ -400,24 +400,22 @@ declare module '@docusaurus/plugin-content-blog' {
   export type ReadingTimeFunction = (params: {
     /** Markdown content. */
     content: string;
+    /** Locale for word segmentation. */
+    locale: string;
     /** Front matter. */
     frontMatter?: BlogPostFrontMatter & {[key: string]: unknown};
-    /** Options accepted by ngryman/reading-time. */
+    /** Options for reading time calculation. */
     options?: ReadingTimeOptions;
   }) => number;
 
   /**
-   * @returns The reading time directly plugged into metadata. `undefined` to
-   * hide reading time for a specific post.
+   * @returns The reading time directly plugged into metadata.
+   * `undefined` to hide reading time for a specific post.
    */
   export type ReadingTimeFunctionOption = (
-    /**
-     * The `options` is not provided by the caller; the user can inject their
-     * own option values into `defaultReadingTime`
-     */
     params: Required<Omit<Parameters<ReadingTimeFunction>[0], 'options'>> & {
       /**
-       * The default reading time implementation from ngryman/reading-time.
+       * The default reading time implementation.
        */
       defaultReadingTime: ReadingTimeFunction;
     },
@@ -523,9 +521,9 @@ declare module '@docusaurus/plugin-content-blog' {
       readingTime: ReadingTimeFunctionOption;
       /** Governs the direction of blog post sorting. */
       sortPosts: 'ascending' | 'descending';
-      /**	Whether to display the last date the doc was updated. */
+      /**	Whether to display the last date the blog post was updated. */
       showLastUpdateTime: boolean;
-      /** Whether to display the author who last updated the doc. */
+      /** Whether to display the author who last updated the blog post. */
       showLastUpdateAuthor: boolean;
       /** An optional function which can be used to transform blog posts
        *  (filter, modify, delete, etc...).
@@ -666,6 +664,10 @@ declare module '@docusaurus/plugin-content-blog' {
     context: LoadContext,
     options: PluginOptions,
   ): Promise<Plugin<BlogContent>>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
 }
 
 declare module '@theme/BlogPostPage' {

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

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+const DEFAULT_WORDS_PER_MINUTE = 200;
+
+/**
+ * Counts the number of words in a string using Intl.Segmenter.
+ * @param content The text content to count words in.
+ * @param locale The locale to use for segmentation.
+ */
+function countWords(content: string, locale: string): number {
+  if (!content) {
+    return 0;
+  }
+  const segmenter = new Intl.Segmenter(locale, {granularity: 'word'});
+  let wordCount = 0;
+  for (const {isWordLike} of segmenter.segment(content)) {
+    if (isWordLike) {
+      wordCount += 1;
+    }
+  }
+  return wordCount;
+}
+
+/**
+ * Calculates the reading time for a given content string using Intl.Segmenter.
+ * @param content The text content to calculate reading time for.
+ * @param locale Required locale string for Intl.Segmenter
+ * @param options Options for reading time calculation.
+ *   - wordsPerMinute: number of words per minute (default 200)
+ * @returns Estimated reading time in minutes (float, rounded to 2 decimals)
+ */
+export function calculateReadingTime(
+  content: string,
+  locale: string,
+  options?: {wordsPerMinute?: number},
+): number {
+  const wordsPerMinute = options?.wordsPerMinute ?? DEFAULT_WORDS_PER_MINUTE;
+  const words = countWords(content, locale);
+  if (words === 0) {
+    return 0;
+  }
+  // Calculate reading time in minutes and round to 2 decimal places
+  return Math.round((words / wordsPerMinute) * 100) / 100;
+}