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

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

.github/workflows/argos.yml

@@ -27,10 +27,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Use Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

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

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

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

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

.github/workflows/build-perf.yml

@@ -41,14 +41,14 @@ jobs:
         DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Track build size changes
-        uses: preactjs/compressed-size-action@946a292cd35bd1088e0d7eb92b69d1a8d5b5d76a # v2
+        uses: preactjs/compressed-size-action@8518045ed95e94e971b83333085e1cb99aa18aa8 # v2.9.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           build-script: build:website:fast
@@ -62,6 +62,7 @@ jobs:
           comment-key: DOCUSAURUS_INFRA_${{ matrix.DOCUSAURUS_INFRA }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
   # Ensures build times stay under reasonable thresholds
   build-time:
@@ -73,9 +74,9 @@ jobs:
         DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -88,6 +89,7 @@ jobs:
         timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 3 || 2  }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
       # Ensure build with a warm cache does not increase too much
       - name: Build (warm cache)
@@ -96,5 +98,6 @@ jobs:
         timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 1 || 2  }}
         env:
           DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
     # TODO post a GitHub comment with build with perf warnings?

.github/workflows/canary-release.yml

@@ -20,11 +20,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/codeql-analysis.yml

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

.github/workflows/continuous-releases.yml

@@ -18,10 +18,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/dependency-review.yml

@@ -13,6 +13,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Dependency Review
-        uses: actions/dependency-review-action@595b5aeba73380359d98a5e087f648dbb0edce1b # 4.7.3
+        uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # 4.8.2

.github/workflows/lighthouse-report.yml

@@ -21,10 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Use Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/lint-autofix.yml

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

.github/workflows/lint.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/showcase-test.yml

@@ -22,9 +22,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Set up Node
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-e2e.yml

@@ -38,12 +38,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['20.0', '20', '22', '24']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -78,9 +78,9 @@ jobs:
     runs-on: windows-8-core
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -109,7 +109,7 @@ jobs:
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: test-website-in-workspace
       - name: Upload Website artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: website-e2e-windows
           path: test-website-in-workspace/build
@@ -124,9 +124,9 @@ jobs:
         variant: [-s, -st]
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -193,9 +193,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn
@@ -233,9 +233,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: lts/*
           cache: yarn

.github/workflows/tests-swizzle.yml

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

.github/workflows/tests-windows.yml

@@ -27,14 +27,14 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        node: ['20.0', '20', '22', '24']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Support longpaths
         run: git config --system core.longpaths true
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -54,6 +54,8 @@ jobs:
         run: yarn workspace website test:swizzle:wrap:ts
       - name: Docusaurus Build
         run: yarn build:website:fast
+        env:
+          DOCUSAURUS_PERF_LOGGER: 'true'
 
       - name: TypeCheck website
         # see https://github.com/facebook/docusaurus/pull/10486

.github/workflows/tests.yml

@@ -27,12 +27,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['20.0', '20', '22', '24']
+        node: ['20.0', '20', '22', '24', '25.1']
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn

.prettierignore

@@ -1,7 +1,7 @@
 dist
 node_modules
 .yarn
-build
+**/build/**
 coverage
 .docusaurus
 .idea
@@ -11,6 +11,8 @@ coverage
 
 jest/vendor
 
+argos/test-results
+
 packages/lqip-loader/lib/
 packages/docusaurus/lib/
 packages/docusaurus-*/lib/*

CHANGELOG.md

@@ -1,5 +1,58 @@
 # Docusaurus Changelog
 
+## 3.9.2 (2025-10-17)
+
+#### :bug: Bug Fix
+
+- `docusaurus-plugin-content-docs`
+  - [#11490](https://github.com/facebook/docusaurus/pull/11490) fix(docs): add support for missing `sidebar_key` front matter attribute ([@slorber](https://github.com/slorber))
+- `docusaurus-cssnano-preset`
+  - [#11487](https://github.com/facebook/docusaurus/pull/11487) fix(cssnano-preset): disable CSS counter minification ([@YDKK](https://github.com/YDKK))
+- `docusaurus-theme-search-algolia`
+  - [#11468](https://github.com/facebook/docusaurus/pull/11468) fix(theme-search-algolia): Fix Algolia AskAI validation logic ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#11431](https://github.com/facebook/docusaurus/pull/11431) fix(theme-translation): add missing Polish (pl) theme translations ([@mariuszkrzaczkowski](https://github.com/mariuszkrzaczkowski))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#11466](https://github.com/facebook/docusaurus/pull/11466) fix(theme): Fix CSS `scroll-margin-top` when clicking footnote items, factorize code ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#11452](https://github.com/facebook/docusaurus/pull/11452) fix(core): allow `i18n.localeConfigs.translate` in validation ([@trofim24](https://github.com/trofim24))
+- `docusaurus-theme-mermaid`
+  - [#11437](https://github.com/facebook/docusaurus/pull/11437) fix(theme-mermaid): Fix Mermaid ELK layout dependency required bug on v3.9 ([@slorber](https://github.com/slorber))
+
+#### :running_woman: Performance
+
+- `docusaurus-theme-mermaid`
+  - [#11438](https://github.com/facebook/docusaurus/pull/11438) perf(theme-mermaid): lazy load the Mermaid library ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-classic`
+  - [#11463](https://github.com/facebook/docusaurus/pull/11463) fix(theme): remove "Edit this page" button from print view ([@richk21](https://github.com/richk21))
+
+#### :robot: Dependencies
+
+- [#11479](https://github.com/facebook/docusaurus/pull/11479) chore(deps): bump stefanzweifel/git-auto-commit-action from 6 to 7 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11480](https://github.com/facebook/docusaurus/pull/11480) chore(deps): bump github/codeql-action from 3.26.5 to 4.30.8 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11481](https://github.com/facebook/docusaurus/pull/11481) chore(deps): bump actions/dependency-review-action from 4.8.0 to 4.8.1 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#11446](https://github.com/facebook/docusaurus/pull/11446) chore(deps): bump actions/dependency-review-action from 4.7.3 to 4.8.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :globe_with_meridians: Translations
+
+- `docusaurus-theme-translations`
+  - [#11484](https://github.com/facebook/docusaurus/pull/11484) fix(translations): improve Arabic theme translations ([@maysara-elshewehy](https://github.com/maysara-elshewehy))
+
+#### Committers: 9
+
+- Alexander Trofimov ([@trofim24](https://github.com/trofim24))
+- Dan Roscigno ([@DanRoscigno](https://github.com/DanRoscigno))
+- Eleni Grosdouli ([@egrosdou01](https://github.com/egrosdou01))
+- Ethan ([@ethanppl](https://github.com/ethanppl))
+- Mariusz Krzaczkowski ([@mariuszkrzaczkowski](https://github.com/mariuszkrzaczkowski))
+- Maysara ([@maysara-elshewehy](https://github.com/maysara-elshewehy))
+- Richa Kiran ([@richk21](https://github.com/richk21))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- [@YDKK](https://github.com/YDKK)
+
 ## 3.9.1 (2025-09-26)
 
 #### :bug: Bug Fix

README.md

@@ -45,7 +45,7 @@ Short on time? Check out our [5-minute tutorial ⏱️](https://tutorial.docusau
 
 - **Customizable**
 
-> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
+> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/blog), and additional support pages, it is also [customizable](https://docusaurus.io/docs/creating-pages) to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/styling-layout).
 
 ## Installation
 

admin/new.docusaurus.io/package.json

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

admin/test-bad-package/package.json

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

argos/package.json

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

examples/classic-typescript/package.json

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

examples/classic/package.json

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

jest/deps.d.ts

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

jest/snapshotPathNormalizer.ts

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

jest/utils/git.ts

@@ -1,63 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import fs from 'fs-extra';
-import os from 'os';
-import path from 'path';
-import shell from 'shelljs';
-
-class Git {
-  constructor(private dir: string) {
-    const res = shell.exec('git init', {cwd: dir, silent: true});
-    if (res.code !== 0) {
-      throw new Error(`git init exited with code ${res.code}.
-stderr: ${res.stderr}
-stdout: ${res.stdout}`);
-    }
-    // Doesn't matter currently
-    shell.exec('git config user.email "test@jc-verse.com"', {
-      cwd: dir,
-      silent: true,
-    });
-    shell.exec('git config user.name "Test"', {cwd: dir, silent: true});
-
-    shell.exec('git commit --allow-empty -m "First commit"', {
-      cwd: dir,
-      silent: true,
-    });
-  }
-  commit(msg: string, date: string, author: string): void {
-    const addRes = shell.exec('git add .', {cwd: this.dir, silent: true});
-    const commitRes = shell.exec(
-      `git commit -m "${msg}" --date "${date}T00:00:00Z" --author "${author}"`,
-      {
-        cwd: this.dir,
-        env: {GIT_COMMITTER_DATE: `${date}T00:00:00Z`},
-        silent: true,
-      },
-    );
-    if (addRes.code !== 0) {
-      throw new Error(`git add exited with code ${addRes.code}.
-stderr: ${addRes.stderr}
-stdout: ${addRes.stdout}`);
-    }
-    if (commitRes.code !== 0) {
-      throw new Error(`git commit exited with code ${commitRes.code}.
-stderr: ${commitRes.stderr}
-stdout: ${commitRes.stdout}`);
-    }
-  }
-}
-
-// This function is sync so the same mock repo can be shared across tests
-export function createTempRepo(): {repoDir: string; git: Git} {
-  const repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'git-test-repo'));
-
-  const git = new Git(repoDir);
-
-  return {repoDir, git};
-}

lerna.json

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

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,10 +22,10 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "commander": "^5.1.0",
-    "execa": "5.1.1",
+    "execa": "^5.1.1",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "prompts": "^2.4.2",

packages/create-docusaurus/src/index.ts

@@ -273,7 +273,10 @@ async function getSiteName(
       return 'A website name is required.';
     }
     const dest = path.resolve(rootDir, siteName);
-    if (await fs.pathExists(dest)) {
+    if (siteName === '.' && (await fs.readdir(dest)).length > 0) {
+      return logger.interpolate`Directory not empty at path=${dest}!`;
+    }
+    if (siteName !== '.' && (await fs.pathExists(dest))) {
       return logger.interpolate`Directory already exists at path=${dest}!`;
     }
     return true;

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

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

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

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

packages/docusaurus-babel/package.json

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

packages/docusaurus-bundler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/bundler",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "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.9.1",
-    "@docusaurus/cssnano-preset": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
+    "@docusaurus/babel": "3.9.2",
+    "@docusaurus/cssnano-preset": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "babel-loader": "^9.2.1",
     "clean-css": "^5.3.3",
     "copy-webpack-plugin": "^11.0.0",

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

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

packages/docusaurus-bundler/src/minification.ts

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

packages/docusaurus-cssnano-preset/package.json

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

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

@@ -13,6 +13,9 @@ const preset: typeof advancedBasePreset = function preset(opts) {
   const advancedPreset = advancedBasePreset({
     autoprefixer: {add: false},
     discardComments: {removeAll: true},
+    // See CodeBlock custom line number bug: https://github.com/facebook/docusaurus/pull/11487
+    /* cSpell:ignore Idents */
+    reduceIdents: {counter: false},
     /* cSpell:ignore zindex */
     zindex: false,
     ...opts,

packages/docusaurus-faster/package.json

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

packages/docusaurus-faster/src/index.ts

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

packages/docusaurus-logger/package.json

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

packages/docusaurus-mdx-loader/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/mdx-loader",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@mdx-js/mdx": "^3.0.0",
     "@slorber/remark-comment": "^1.0.0",
     "escape-html": "^1.0.3",
@@ -44,7 +44,7 @@
     "webpack": "^5.88.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.9.1",
+    "@docusaurus/types": "3.9.2",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",

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

@@ -6,7 +6,6 @@
  */
 
 import path from 'path';
-import url from 'url';
 import fs from 'fs-extra';
 import {
   toMessageRelativeFilePath,
@@ -15,6 +14,7 @@ import {
   findAsyncSequential,
   getFileLoaderUtils,
   parseURLOrPath,
+  parseLocalURLPath,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import {imageSizeFromFile} from 'image-size/fromFile';
@@ -207,11 +207,11 @@ async function processImageNode(target: Target, context: Context) {
     return;
   }
 
-  const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol || !parsedUrl.pathname) {
-    // pathname:// is an escape hatch, in case user does not want her images to
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
+    // pathname:// is an escape hatch, in case the user does not want images to
     // be converted to require calls going through webpack loader
-    if (parsedUrl.protocol === 'pathname:') {
+    if (parseURLOrPath(node.url).protocol === 'pathname:') {
       node.url = node.url.replace('pathname://', '');
     }
     return;
@@ -220,7 +220,7 @@ async function processImageNode(target: Target, context: Context) {
   // We decode it first because Node Url.pathname is always encoded
   // while the image file-system path are not.
   // See https://github.com/facebook/docusaurus/discussions/10720
-  const decodedPathname = decodeURIComponent(parsedUrl.pathname);
+  const decodedPathname = decodeURIComponent(localUrlPath.pathname);
 
   // We try to convert image urls without protocol to images with require calls
   // going through webpack ensures that image assets exist at build time

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

@@ -6,7 +6,6 @@
  */
 
 import path from 'path';
-import url from 'url';
 import fs from 'fs-extra';
 import {
   toMessageRelativeFilePath,
@@ -15,6 +14,7 @@ import {
   findAsyncSequential,
   getFileLoaderUtils,
   parseURLOrPath,
+  parseLocalURLPath,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import logger from '@docusaurus/logger';
@@ -209,21 +209,22 @@ async function processLinkNode(target: Target, context: Context) {
     return;
   }
 
-  const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol || !parsedUrl.pathname) {
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
     // Don't process pathname:// here, it's used by the <Link> component
     return;
   }
-  const hasSiteAlias = parsedUrl.pathname.startsWith('@site/');
+
+  const hasSiteAlias = localUrlPath.pathname.startsWith('@site/');
   const hasAssetLikeExtension =
-    path.extname(parsedUrl.pathname) &&
-    !parsedUrl.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
+    path.extname(localUrlPath.pathname) &&
+    !localUrlPath.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
   if (!hasSiteAlias && !hasAssetLikeExtension) {
     return;
   }
 
   const localFilePath = await getLocalFileAbsolutePath(
-    decodeURIComponent(parsedUrl.pathname),
+    decodeURIComponent(localUrlPath.pathname),
     context,
   );
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/module-type-aliases",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Docusaurus module type aliases.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -12,7 +12,7 @@
     "directory": "packages/docusaurus-module-type-aliases"
   },
   "dependencies": {
-    "@docusaurus/types": "3.9.1",
+    "@docusaurus/types": "3.9.2",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-client-redirects",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "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.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "eta": "^2.2.0",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "tslib": "^2.6.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.9.1"
+    "@docusaurus/types": "3.9.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,14 +31,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/mdx-loader": "3.9.1",
-    "@docusaurus/theme-common": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/mdx-loader": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "cheerio": "1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",

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

@@ -0,0 +1,637 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`buildAllRoutes works for realistic blog post 2`] = `
+[
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post1.md",
+    },
+    "modules": {
+      "content": "@site/blog/post1.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post1",
+  },
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post2.md",
+    },
+    "modules": {
+      "content": "@site/blog/post2.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post2",
+  },
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post3.md",
+    },
+    "modules": {
+      "content": "@site/blog/post3.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post3",
+  },
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post4.md",
+    },
+    "modules": {
+      "content": "@site/blog/post4.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post4",
+  },
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post5.md",
+    },
+    "modules": {
+      "content": "@site/blog/post5.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post5",
+  },
+  {
+    "component": "@theme/BlogPostPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "metadata": {
+      "lastUpdatedAt": undefined,
+      "sourceFilePath": "blog/post6.md",
+    },
+    "modules": {
+      "content": "@site/blog/post6.md",
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/post6",
+  },
+  {
+    "component": "@theme/BlogListPage",
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post1.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post2.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog",
+    "props": {
+      "metadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": "/blog/page/2",
+        "page": 1,
+        "permalink": "/blog",
+        "postsPerPage": 2,
+        "previousPage": undefined,
+        "totalCount": 5,
+        "totalPages": 3,
+      },
+    },
+  },
+  {
+    "component": "@theme/BlogListPage",
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post4.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post5.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/page/2",
+    "props": {
+      "metadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": "/blog/page/3",
+        "page": 2,
+        "permalink": "/blog/page/2",
+        "postsPerPage": 2,
+        "previousPage": "/blog",
+        "totalCount": 5,
+        "totalPages": 3,
+      },
+    },
+  },
+  {
+    "component": "@theme/BlogListPage",
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post6.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/page/3",
+    "props": {
+      "metadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": undefined,
+        "page": 3,
+        "permalink": "/blog/page/3",
+        "postsPerPage": 2,
+        "previousPage": "/blog/page/2",
+        "totalCount": 5,
+        "totalPages": 3,
+      },
+    },
+  },
+  {
+    "component": "@theme/BlogArchivePage",
+    "exact": true,
+    "path": "/blog/archive",
+    "props": {
+      "archive": {
+        "blogPosts": [
+          {
+            "content": "Content for post1",
+            "id": "post1",
+            "metadata": {
+              "authors": [
+                {
+                  "key": "author1",
+                },
+              ],
+              "date": 2020-01-01T00:00:00.000Z,
+              "description": "Description for post1",
+              "frontMatter": {},
+              "permalink": "/blog/post1",
+              "readingTime": 2,
+              "source": "@site/blog/post1.md",
+              "tags": [],
+              "title": "Title for post1",
+            },
+          },
+          {
+            "content": "Content for post2",
+            "id": "post2",
+            "metadata": {
+              "authors": [
+                {
+                  "key": "author1",
+                },
+              ],
+              "date": 2020-01-01T00:00:00.000Z,
+              "description": "Description for post2",
+              "frontMatter": {},
+              "permalink": "/blog/post2",
+              "readingTime": 2,
+              "source": "@site/blog/post2.md",
+              "tags": [],
+              "title": "Title for post2",
+            },
+          },
+          {
+            "content": "Content for post4",
+            "id": "post4",
+            "metadata": {
+              "authors": [
+                {
+                  "key": "author1",
+                },
+                {
+                  "key": "author2",
+                },
+              ],
+              "date": 2020-01-01T00:00:00.000Z,
+              "description": "Description for post4",
+              "frontMatter": {},
+              "permalink": "/blog/post4",
+              "readingTime": 2,
+              "source": "@site/blog/post4.md",
+              "tags": [],
+              "title": "Title for post4",
+            },
+          },
+          {
+            "content": "Content for post5",
+            "id": "post5",
+            "metadata": {
+              "authors": [
+                {
+                  "key": "author2",
+                },
+                {
+                  "key": "author3",
+                },
+              ],
+              "date": 2020-01-01T00:00:00.000Z,
+              "description": "Description for post5",
+              "frontMatter": {},
+              "permalink": "/blog/post5",
+              "readingTime": 2,
+              "source": "@site/blog/post5.md",
+              "tags": [],
+              "title": "Title for post5",
+            },
+          },
+          {
+            "content": "Content for post6",
+            "id": "post6",
+            "metadata": {
+              "authors": [],
+              "date": 2020-01-01T00:00:00.000Z,
+              "description": "Description for post6",
+              "frontMatter": {},
+              "permalink": "/blog/post6",
+              "readingTime": 2,
+              "source": "@site/blog/post6.md",
+              "tags": [],
+              "title": "Title for post6",
+            },
+          },
+        ],
+      },
+    },
+  },
+  {
+    "component": "@theme/Blog/Pages/BlogAuthorsListPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "modules": {
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/authors",
+    "props": {
+      "authors": [
+        {
+          "count": 3,
+          "key": "author1",
+          "name": "Author 1",
+          "page": {
+            "permalink": "/blog/authors/author1",
+          },
+        },
+        {
+          "count": 2,
+          "key": "author2",
+          "name": "Author 2",
+          "page": null,
+        },
+        {
+          "count": 1,
+          "key": "author3",
+          "name": "Author 3",
+          "page": {
+            "permalink": "/blog/authors/author3",
+          },
+        },
+      ],
+    },
+  },
+  {
+    "component": "@theme/Blog/Pages/BlogAuthorsPostsPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post1.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post2.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/authors/author1",
+    "props": {
+      "author": {
+        "count": 3,
+        "key": "author1",
+        "name": "Author 1",
+        "page": {
+          "permalink": "/blog/authors/author1",
+        },
+      },
+      "listMetadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": "/blog/authors/author1/page/2",
+        "page": 1,
+        "permalink": "/blog/authors/author1",
+        "postsPerPage": 2,
+        "previousPage": undefined,
+        "totalCount": 3,
+        "totalPages": 2,
+      },
+    },
+  },
+  {
+    "component": "@theme/Blog/Pages/BlogAuthorsPostsPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post4.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/authors/author1/page/2",
+    "props": {
+      "author": {
+        "count": 3,
+        "key": "author1",
+        "name": "Author 1",
+        "page": {
+          "permalink": "/blog/authors/author1",
+        },
+      },
+      "listMetadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": undefined,
+        "page": 2,
+        "permalink": "/blog/authors/author1/page/2",
+        "postsPerPage": 2,
+        "previousPage": "/blog/authors/author1",
+        "totalCount": 3,
+        "totalPages": 2,
+      },
+    },
+  },
+  {
+    "component": "@theme/Blog/Pages/BlogAuthorsPostsPage",
+    "context": {
+      "blogMetadata": "@aliased/data/blogMetadata-default.json",
+    },
+    "exact": true,
+    "modules": {
+      "items": [
+        {
+          "content": {
+            "__import": true,
+            "path": "@site/blog/post5.md",
+            "query": {
+              "truncated": true,
+            },
+          },
+        },
+      ],
+      "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+    },
+    "path": "/blog/authors/author3",
+    "props": {
+      "author": {
+        "count": 1,
+        "key": "author3",
+        "name": "Author 3",
+        "page": {
+          "permalink": "/blog/authors/author3",
+        },
+      },
+      "listMetadata": {
+        "blogDescription": "Custom blog description",
+        "blogTitle": "Custom blog title",
+        "nextPage": undefined,
+        "page": 1,
+        "permalink": "/blog/authors/author3",
+        "postsPerPage": 2,
+        "previousPage": undefined,
+        "totalCount": 1,
+        "totalPages": 1,
+      },
+    },
+  },
+]
+`;
+
+exports[`buildAllRoutes works for realistic blog post 3`] = `
+{
+  "blog-post-list-prop-default.json": {
+    "items": [
+      {
+        "date": 2020-01-01T00:00:00.000Z,
+        "permalink": "/blog/post1",
+        "title": "Title for post1",
+        "unlisted": undefined,
+      },
+      {
+        "date": 2020-01-01T00:00:00.000Z,
+        "permalink": "/blog/post2",
+        "title": "Title for post2",
+        "unlisted": undefined,
+      },
+      {
+        "date": 2020-01-01T00:00:00.000Z,
+        "permalink": "/blog/post3",
+        "title": "Title for post3",
+        "unlisted": true,
+      },
+      {
+        "date": 2020-01-01T00:00:00.000Z,
+        "permalink": "/blog/post4",
+        "title": "Title for post4",
+        "unlisted": undefined,
+      },
+      {
+        "date": 2020-01-01T00:00:00.000Z,
+        "permalink": "/blog/post5",
+        "title": "Title for post5",
+        "unlisted": undefined,
+      },
+    ],
+    "title": "Custom blog sidebar title",
+  },
+  "blogMetadata-default.json": {
+    "authorsListPath": "/blog/authors",
+    "blogBasePath": "/blog",
+    "blogTitle": "Custom blog title",
+  },
+  "site-blog-post-1-md-235.json": {
+    "authors": [
+      {
+        "key": "author1",
+      },
+    ],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post1",
+    "frontMatter": {},
+    "permalink": "/blog/post1",
+    "readingTime": 2,
+    "source": "@site/blog/post1.md",
+    "tags": [],
+    "title": "Title for post1",
+  },
+  "site-blog-post-2-md-b42.json": {
+    "authors": [
+      {
+        "key": "author1",
+      },
+    ],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post2",
+    "frontMatter": {},
+    "permalink": "/blog/post2",
+    "readingTime": 2,
+    "source": "@site/blog/post2.md",
+    "tags": [],
+    "title": "Title for post2",
+  },
+  "site-blog-post-3-md-3b7.json": {
+    "authors": [
+      {
+        "key": "author3",
+      },
+    ],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post3",
+    "frontMatter": {},
+    "permalink": "/blog/post3",
+    "readingTime": 2,
+    "source": "@site/blog/post3.md",
+    "tags": [],
+    "title": "Title for post3",
+    "unlisted": true,
+  },
+  "site-blog-post-4-md-15a.json": {
+    "authors": [
+      {
+        "key": "author1",
+      },
+      {
+        "key": "author2",
+      },
+    ],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post4",
+    "frontMatter": {},
+    "permalink": "/blog/post4",
+    "readingTime": 2,
+    "source": "@site/blog/post4.md",
+    "tags": [],
+    "title": "Title for post4",
+  },
+  "site-blog-post-5-md-274.json": {
+    "authors": [
+      {
+        "key": "author2",
+      },
+      {
+        "key": "author3",
+      },
+    ],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post5",
+    "frontMatter": {},
+    "permalink": "/blog/post5",
+    "readingTime": 2,
+    "source": "@site/blog/post5.md",
+    "tags": [],
+    "title": "Title for post5",
+  },
+  "site-blog-post-6-md-3ca.json": {
+    "authors": [],
+    "date": 2020-01-01T00:00:00.000Z,
+    "description": "Description for post6",
+    "frontMatter": {},
+    "permalink": "/blog/post6",
+    "readingTime": 2,
+    "source": "@site/blog/post6.md",
+    "tags": [],
+    "title": "Title for post6",
+  },
+}
+`;

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

@@ -24,24 +24,7 @@ exports[`getContentTranslationFiles returns translation files matching snapshot
 
 exports[`translateContent falls back when translation is incomplete 1`] = `
 {
-  "blogListPaginated": [
-    {
-      "items": [
-        "hello",
-      ],
-      "metadata": {
-        "blogDescription": "Someone's random blog",
-        "blogTitle": "My blog",
-        "nextPage": undefined,
-        "page": 1,
-        "permalink": "/",
-        "postsPerPage": 10,
-        "previousPage": undefined,
-        "totalCount": 1,
-        "totalPages": 1,
-      },
-    },
-  ],
+  "blogDescription": "Someone's random blog",
   "blogPosts": [
     {
       "content": "",
@@ -63,29 +46,13 @@ exports[`translateContent falls back when translation is incomplete 1`] = `
   "blogSidebarTitle": "All my posts",
   "blogTags": {},
   "blogTagsListPath": "/tags",
+  "blogTitle": "My blog",
 }
 `;
 
 exports[`translateContent returns translated loaded 1`] = `
 {
-  "blogListPaginated": [
-    {
-      "items": [
-        "hello",
-      ],
-      "metadata": {
-        "blogDescription": "Someone's random blog (translated)",
-        "blogTitle": "My blog (translated)",
-        "nextPage": undefined,
-        "page": 1,
-        "permalink": "/",
-        "postsPerPage": 10,
-        "previousPage": undefined,
-        "totalCount": 1,
-        "totalPages": 1,
-      },
-    },
-  ],
+  "blogDescription": "Someone's random blog (translated)",
   "blogPosts": [
     {
       "content": "",
@@ -107,5 +74,6 @@ exports[`translateContent returns translated loaded 1`] = `
   "blogSidebarTitle": "All my posts (translated)",
   "blogTags": {},
   "blogTagsListPath": "/tags",
+  "blogTitle": "My blog (translated)",
 }
 `;

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

@@ -8,7 +8,10 @@
 import {jest} from '@jest/globals';
 import path from 'path';
 import fs from 'fs-extra';
-import {DEFAULT_PARSE_FRONT_MATTER} from '@docusaurus/utils';
+import {
+  DEFAULT_PARSE_FRONT_MATTER,
+  DEFAULT_VCS_CONFIG,
+} from '@docusaurus/utils';
 import {fromPartial} from '@total-typescript/shoehorn';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
 import tree from 'tree-node-cli';
@@ -51,7 +54,7 @@ function getBlogContentPaths(siteDir: string): BlogContentPaths {
 }
 
 async function testGenerateFeeds(
-  context: LoadContext,
+  contextInput: LoadContext,
   optionsInput: Options,
 ): Promise<void> {
   const options = validateOptions({
@@ -62,6 +65,17 @@ async function testGenerateFeeds(
     options: optionsInput,
   });
 
+  const context: LoadContext = {
+    ...contextInput,
+    siteConfig: {
+      ...contextInput.siteConfig,
+      future: {
+        ...contextInput.siteConfig?.future,
+        experimental_vcs: DEFAULT_VCS_CONFIG,
+      },
+    },
+  };
+
   const contentPaths = getBlogContentPaths(context.siteDir);
   const authorsMap = await getAuthorsMap({
     contentPaths,

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

@@ -8,12 +8,7 @@
 import {jest} from '@jest/globals';
 import * as path from 'path';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
-import {
-  posixPath,
-  getFileCommitDate,
-  LAST_UPDATE_FALLBACK,
-  getLocaleConfig,
-} from '@docusaurus/utils';
+import {posixPath, getLocaleConfig, TEST_VCS} from '@docusaurus/utils';
 import {DEFAULT_FUTURE_CONFIG} from '@docusaurus/core/src/server/configValidation';
 import pluginContentBlog from '../index';
 import {validateOptions} from '../options';
@@ -32,6 +27,10 @@ import type {
   EditUrlFunction,
 } from '@docusaurus/plugin-content-blog';
 
+async function getFileCreationDate(filePath: string): Promise<Date> {
+  return new Date((await TEST_VCS.getFileCreationInfo(filePath)).timestamp);
+}
+
 const markdown: MarkdownConfig = {
   format: 'mdx',
   mermaid: true,
@@ -561,9 +560,7 @@ describe('blog plugin', () => {
     const blogPosts = await getBlogPosts(siteDir);
     const noDateSource = path.posix.join('@site', PluginPath, 'no date.md');
     const noDateSourceFile = path.posix.join(siteDir, PluginPath, 'no date.md');
-    // We know the file exists and we know we have git
-    const result = await getFileCommitDate(noDateSourceFile, {age: 'oldest'});
-    const noDateSourceTime = result.date;
+    const noDateSourceTime = await getFileCreationDate(noDateSourceFile);
 
     expect({
       ...getByTitle(blogPosts, 'no date').metadata,
@@ -641,10 +638,7 @@ describe('blog plugin', () => {
       },
       DefaultI18N,
     );
-    const {blogPosts, blogTags, blogListPaginated} =
-      (await plugin.loadContent!())!;
-
-    expect(blogListPaginated).toHaveLength(3);
+    const {blogPosts, blogTags} = (await plugin.loadContent!())!;
 
     expect(Object.keys(blogTags)).toHaveLength(2);
     expect(blogTags).toMatchSnapshot();
@@ -674,29 +668,23 @@ describe('last update', () => {
     );
     const {blogPosts} = (await plugin.loadContent!())!;
 
+    const TestLastUpdate = await TEST_VCS.getFileLastUpdateInfo('any path');
+
     expect(blogPosts[0]?.metadata.lastUpdatedBy).toBe('seb');
     expect(blogPosts[0]?.metadata.lastUpdatedAt).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+      lastUpdateFor('2021-01-01'),
     );
 
-    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedBy,
-    );
+    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBe(TestLastUpdate.author);
     expect(blogPosts[1]?.metadata.lastUpdatedAt).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+      lastUpdateFor('2021-01-01'),
     );
 
     expect(blogPosts[2]?.metadata.lastUpdatedBy).toBe('seb');
-    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(
-      lastUpdateFor('2021-01-01'),
-    );
+    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(TestLastUpdate.timestamp);
 
-    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedBy,
-    );
-    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(
-      lastUpdateFor('2021-01-01'),
-    );
+    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBe(TestLastUpdate.author);
+    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(TestLastUpdate.timestamp);
   });
 
   it('time only', async () => {
@@ -710,29 +698,27 @@ describe('last update', () => {
     );
     const {blogPosts} = (await plugin.loadContent!())!;
 
-    expect(blogPosts[0]?.metadata.title).toBe('Author');
+    const TestLastUpdate = await TEST_VCS.getFileLastUpdateInfo('any path');
+
+    expect(blogPosts[0]?.metadata.title).toBe('Both');
     expect(blogPosts[0]?.metadata.lastUpdatedBy).toBeUndefined();
     expect(blogPosts[0]?.metadata.lastUpdatedAt).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+      lastUpdateFor('2021-01-01'),
     );
 
-    expect(blogPosts[1]?.metadata.title).toBe('Nothing');
+    expect(blogPosts[1]?.metadata.title).toBe('Last update date');
     expect(blogPosts[1]?.metadata.lastUpdatedBy).toBeUndefined();
     expect(blogPosts[1]?.metadata.lastUpdatedAt).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+      lastUpdateFor('2021-01-01'),
     );
 
-    expect(blogPosts[2]?.metadata.title).toBe('Both');
+    expect(blogPosts[2]?.metadata.title).toBe('Author');
     expect(blogPosts[2]?.metadata.lastUpdatedBy).toBeUndefined();
-    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(
-      lastUpdateFor('2021-01-01'),
-    );
+    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(TestLastUpdate.timestamp);
 
-    expect(blogPosts[3]?.metadata.title).toBe('Last update date');
+    expect(blogPosts[3]?.metadata.title).toBe('Nothing');
     expect(blogPosts[3]?.metadata.lastUpdatedBy).toBeUndefined();
-    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(
-      lastUpdateFor('2021-01-01'),
-    );
+    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(TestLastUpdate.timestamp);
   });
 
   it('author only', async () => {
@@ -746,20 +732,18 @@ describe('last update', () => {
     );
     const {blogPosts} = (await plugin.loadContent!())!;
 
+    const TestLastUpdate = await TEST_VCS.getFileLastUpdateInfo('any path');
+
     expect(blogPosts[0]?.metadata.lastUpdatedBy).toBe('seb');
     expect(blogPosts[0]?.metadata.lastUpdatedAt).toBeUndefined();
 
-    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedBy,
-    );
+    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBe(TestLastUpdate.author);
     expect(blogPosts[1]?.metadata.lastUpdatedAt).toBeUndefined();
 
     expect(blogPosts[2]?.metadata.lastUpdatedBy).toBe('seb');
     expect(blogPosts[2]?.metadata.lastUpdatedAt).toBeUndefined();
 
-    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBe(
-      LAST_UPDATE_FALLBACK.lastUpdatedBy,
-    );
+    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBe(TestLastUpdate.author);
     expect(blogPosts[3]?.metadata.lastUpdatedAt).toBeUndefined();
   });
 

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

@@ -0,0 +1,324 @@
+/**
+ * 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 * as _ from 'lodash';
+import {fromPartial} from '@total-typescript/shoehorn';
+import {buildAllRoutes} from '../routes';
+import {DEFAULT_OPTIONS} from '../options';
+import type {PartialDeep} from '@total-typescript/shoehorn';
+import type {BlogPost, BlogPostMetadata} from '@docusaurus/plugin-content-blog';
+
+type Params = Parameters<typeof buildAllRoutes>[0];
+
+async function testBuildAllRoutes(overrides: PartialDeep<Params> = {}) {
+  const createData = jest.fn(
+    async (name: string, _data: unknown) => `/data/${name}`,
+  );
+
+  const params: Params = fromPartial<Params>({
+    baseUrl: '/',
+    aliasedSource: (str: string) => `@aliased${str}`,
+    ...overrides,
+
+    content: {
+      blogTitle: 'Blog Title',
+      blogDescription: 'Blog Description',
+      blogSidebarTitle: 'Blog Sidebar Title',
+      authorsMap: {},
+      blogTagsListPath: '',
+      blogTags: {},
+      blogPosts: [],
+      ...overrides?.content,
+    },
+    options: {
+      ...DEFAULT_OPTIONS,
+      ...overrides?.options,
+    },
+    actions: {
+      createData,
+      ...overrides?.actions,
+    },
+  });
+
+  const routes = await buildAllRoutes(params);
+
+  const data = Object.fromEntries(
+    createData.mock.calls.map((call) => [call[0], call[1]]),
+  );
+
+  function getRouteByPath(path: string) {
+    const route = routes.find((r) => r.path === path);
+    if (!route) {
+      throw new Error(`Route not found for path: ${path}`);
+    }
+    return route;
+  }
+
+  function getRoutesByComponent(component: string) {
+    return routes.filter((r) => r.component === component);
+  }
+
+  return {routes, data, utils: {getRouteByPath, getRoutesByComponent}};
+}
+
+function blogPost(overrides: PartialDeep<BlogPost> = {}): BlogPost {
+  const id = overrides.id ?? 'blog-post';
+  return fromPartial<BlogPost>({
+    id,
+    content: `Content for ${id}`,
+    ...overrides,
+    metadata: fromPartial<BlogPostMetadata>({
+      title: `Title for ${id}`,
+      description: `Description for ${id}`,
+      permalink: `/blog/${id}`,
+      source: `@site/blog/${id}.md`,
+      date: new Date('2020-01-01'),
+      tags: [],
+      readingTime: 2,
+      authors: [],
+      frontMatter: {
+        ...overrides?.metadata?.frontMatter,
+      },
+      ...overrides?.metadata,
+    }),
+  });
+}
+
+describe('buildAllRoutes', () => {
+  it('works for empty blog', async () => {
+    const {routes, data} = await testBuildAllRoutes({
+      content: {
+        blogPosts: [],
+      },
+    });
+
+    expect(routes).toMatchInlineSnapshot(`
+      [
+        {
+          "component": "@theme/BlogListPage",
+          "exact": true,
+          "modules": {
+            "items": [],
+            "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+          },
+          "path": "/blog",
+          "props": {
+            "metadata": {
+              "blogDescription": "Blog Description",
+              "blogTitle": "Blog Title",
+              "nextPage": undefined,
+              "page": 1,
+              "permalink": "/blog",
+              "postsPerPage": 10,
+              "previousPage": undefined,
+              "totalCount": 0,
+              "totalPages": 1,
+            },
+          },
+        },
+      ]
+    `);
+    expect(data).toMatchInlineSnapshot(`
+      {
+        "blog-post-list-prop-default.json": {
+          "items": [],
+          "title": "Blog Sidebar Title",
+        },
+        "blogMetadata-default.json": {
+          "authorsListPath": "/blog/authors",
+          "blogBasePath": "/blog",
+          "blogTitle": "Blog Title",
+        },
+      }
+    `);
+  });
+
+  it('works for single blog post', async () => {
+    const {routes, data} = await testBuildAllRoutes({
+      content: {
+        blogPosts: [blogPost()],
+      },
+    });
+
+    expect(routes).toMatchInlineSnapshot(`
+      [
+        {
+          "component": "@theme/BlogPostPage",
+          "context": {
+            "blogMetadata": "@aliased/data/blogMetadata-default.json",
+          },
+          "exact": true,
+          "metadata": {
+            "lastUpdatedAt": undefined,
+            "sourceFilePath": "blog/blog-post.md",
+          },
+          "modules": {
+            "content": "@site/blog/blog-post.md",
+            "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+          },
+          "path": "/blog/blog-post",
+        },
+        {
+          "component": "@theme/BlogListPage",
+          "exact": true,
+          "modules": {
+            "items": [
+              {
+                "content": {
+                  "__import": true,
+                  "path": "@site/blog/blog-post.md",
+                  "query": {
+                    "truncated": true,
+                  },
+                },
+              },
+            ],
+            "sidebar": "@aliased/data/blog-post-list-prop-default.json",
+          },
+          "path": "/blog",
+          "props": {
+            "metadata": {
+              "blogDescription": "Blog Description",
+              "blogTitle": "Blog Title",
+              "nextPage": undefined,
+              "page": 1,
+              "permalink": "/blog",
+              "postsPerPage": 10,
+              "previousPage": undefined,
+              "totalCount": 1,
+              "totalPages": 1,
+            },
+          },
+        },
+        {
+          "component": "@theme/BlogArchivePage",
+          "exact": true,
+          "path": "/blog/archive",
+          "props": {
+            "archive": {
+              "blogPosts": [
+                {
+                  "content": "Content for blog-post",
+                  "id": "blog-post",
+                  "metadata": {
+                    "authors": [],
+                    "date": 2020-01-01T00:00:00.000Z,
+                    "description": "Description for blog-post",
+                    "frontMatter": {},
+                    "permalink": "/blog/blog-post",
+                    "readingTime": 2,
+                    "source": "@site/blog/blog-post.md",
+                    "tags": [],
+                    "title": "Title for blog-post",
+                  },
+                },
+              ],
+            },
+          },
+        },
+      ]
+    `);
+    expect(data).toMatchInlineSnapshot(`
+      {
+        "blog-post-list-prop-default.json": {
+          "items": [
+            {
+              "date": 2020-01-01T00:00:00.000Z,
+              "permalink": "/blog/blog-post",
+              "title": "Title for blog-post",
+              "unlisted": undefined,
+            },
+          ],
+          "title": "Blog Sidebar Title",
+        },
+        "blogMetadata-default.json": {
+          "authorsListPath": "/blog/authors",
+          "blogBasePath": "/blog",
+          "blogTitle": "Blog Title",
+        },
+        "site-blog-blog-post-md-0d7.json": {
+          "authors": [],
+          "date": 2020-01-01T00:00:00.000Z,
+          "description": "Description for blog-post",
+          "frontMatter": {},
+          "permalink": "/blog/blog-post",
+          "readingTime": 2,
+          "source": "@site/blog/blog-post.md",
+          "tags": [],
+          "title": "Title for blog-post",
+        },
+      }
+    `);
+  });
+
+  it('works for realistic blog post', async () => {
+    const {routes, data} = await testBuildAllRoutes({
+      options: {
+        postsPerPage: 2,
+      },
+      content: {
+        blogTitle: 'Custom blog title',
+        blogDescription: 'Custom blog description',
+        blogSidebarTitle: 'Custom blog sidebar title',
+
+        blogPosts: [
+          blogPost({id: 'post1', metadata: {authors: [{key: 'author1'}]}}),
+          blogPost({id: 'post2', metadata: {authors: [{key: 'author1'}]}}),
+          blogPost({
+            id: 'post3',
+            metadata: {
+              authors: [{key: 'author3'}],
+              unlisted: true,
+            },
+          }),
+          blogPost({
+            id: 'post4',
+            metadata: {
+              authors: [{key: 'author1'}, {key: 'author2'}],
+            },
+          }),
+          blogPost({
+            id: 'post5',
+            metadata: {authors: [{key: 'author2'}, {key: 'author3'}]},
+          }),
+          blogPost({id: 'post6'}),
+        ],
+
+        authorsMap: {
+          author1: {
+            key: 'author1',
+            name: 'Author 1',
+            page: {permalink: '/blog/authors/author1'},
+          },
+          author2: {
+            key: 'author2',
+            name: 'Author 2',
+            page: null,
+          },
+          author3: {
+            key: 'author3',
+            name: 'Author 3',
+            page: {permalink: '/blog/authors/author3'},
+          },
+        },
+      },
+    });
+
+    expect(_.countBy(routes, 'component')).toMatchInlineSnapshot(`
+      {
+        "@theme/Blog/Pages/BlogAuthorsListPage": 1,
+        "@theme/Blog/Pages/BlogAuthorsPostsPage": 3,
+        "@theme/BlogArchivePage": 1,
+        "@theme/BlogListPage": 3,
+        "@theme/BlogPostPage": 6,
+      }
+    `);
+
+    expect(routes).toMatchSnapshot();
+    expect(data).toMatchSnapshot();
+  });
+});

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

@@ -6,6 +6,7 @@
  */
 
 import {updateTranslationFileMessages} from '@docusaurus/utils';
+import {fromPartial} from '@total-typescript/shoehorn';
 import {getTranslationFiles, translateContent} from '../translations';
 import {DEFAULT_OPTIONS} from '../options';
 import type {
@@ -16,13 +17,13 @@ import type {
 
 const sampleBlogOptions: PluginOptions = {
   ...DEFAULT_OPTIONS,
-  blogSidebarTitle: 'All my posts',
   blogTitle: 'My blog',
   blogDescription: "Someone's random blog",
+  blogSidebarTitle: 'All my posts',
 };
 
 const sampleBlogPosts: BlogPost[] = [
-  {
+  fromPartial({
     id: 'hello',
     metadata: {
       permalink: '/blog/2021/06/19/hello',
@@ -37,27 +38,13 @@ const sampleBlogPosts: BlogPost[] = [
       unlisted: false,
     },
     content: '',
-  },
+  }),
 ];
 
 const sampleBlogContent: BlogContent = {
+  blogTitle: sampleBlogOptions.blogTitle,
+  blogDescription: sampleBlogOptions.blogDescription,
   blogSidebarTitle: sampleBlogOptions.blogSidebarTitle,
-  blogListPaginated: [
-    {
-      items: ['hello'],
-      metadata: {
-        permalink: '/',
-        page: 1,
-        postsPerPage: 10,
-        totalPages: 1,
-        totalCount: 1,
-        previousPage: undefined,
-        nextPage: undefined,
-        blogTitle: sampleBlogOptions.blogTitle,
-        blogDescription: sampleBlogOptions.blogDescription,
-      },
-    },
-  ],
   blogPosts: sampleBlogPosts,
   blogTags: {},
   blogTagsListPath: '/tags',

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

@@ -19,7 +19,6 @@ import {
   Globby,
   groupTaggedItems,
   getTagVisibility,
-  getFileCommitDate,
   getContentPathList,
   isUnlisted,
   isDraft,
@@ -225,6 +224,7 @@ async function processBlogSourceFile(
     siteConfig: {
       baseUrl,
       markdown: {parseFrontMatter},
+      future: {experimental_vcs: vcs},
     },
     siteDir,
     i18n,
@@ -257,6 +257,7 @@ async function processBlogSourceFile(
     blogSourceAbsolute,
     options,
     frontMatter.last_update,
+    vcs,
   );
 
   const draft = isDraft({frontMatter});
@@ -285,17 +286,11 @@ async function processBlogSourceFile(
       return parsedBlogFileName.date;
     }
 
-    try {
-      const result = await getFileCommitDate(blogSourceAbsolute, {
-        age: 'oldest',
-        includeAuthor: false,
-      });
-
-      return result.date;
-    } catch (err) {
-      logger.warn(err);
+    const result = await vcs.getFileCreationInfo(blogSourceAbsolute);
+    if (result == null) {
       return (await fs.stat(blogSourceAbsolute)).birthtime;
     }
+    return new Date(result.timestamp);
   }
 
   const date = await getDate();
@@ -406,6 +401,8 @@ export async function generateBlogPosts(
     ignore: exclude,
   });
 
+  // TODO this should be done outside of this function
+  //  directly in plugin loadContent()
   const tagsFile = await getTagsFile({contentPaths, tags: options.tags});
 
   async function doProcessBlogSourceFile(blogSourceFile: string) {

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

@@ -17,7 +17,6 @@ import {
   createAbsoluteFilePathMatcher,
   getContentPathList,
   getDataFilePath,
-  DEFAULT_PLUGIN_ID,
   resolveMarkdownLinkPathname,
   getLocaleConfig,
 } from '@docusaurus/utils';
@@ -25,7 +24,6 @@ import {getTagsFilePathsToWatch} from '@docusaurus/utils-validation';
 import {createMDXLoaderItem} from '@docusaurus/mdx-loader';
 import {
   getBlogTags,
-  paginateBlogPosts,
   shouldBeListed,
   applyProcessBlogPosts,
   generateBlogPosts,
@@ -45,7 +43,6 @@ import type {
   Assets,
   BlogTags,
   BlogContent,
-  BlogPaginated,
 } from '@docusaurus/plugin-content-blog';
 import type {RuleSetRule, RuleSetUseItem} from 'webpack';
 
@@ -85,7 +82,7 @@ export default async function pluginContentBlog(
         })
       : undefined,
   };
-  const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
+  const pluginId = options.id;
 
   const pluginDataDirRoot = path.join(generatedFilesDir, PluginName);
   const dataDir = path.join(pluginDataDirRoot, pluginId);
@@ -260,9 +257,10 @@ export default async function pluginContentBlog(
 
       if (!blogPosts.length) {
         return {
+          blogTitle,
+          blogDescription,
           blogSidebarTitle,
           blogPosts: [],
-          blogListPaginated: [],
           blogTags: {},
           blogTagsListPath,
           authorsMap,
@@ -291,15 +289,9 @@ export default async function pluginContentBlog(
         }
       });
 
-      const blogListPaginated: BlogPaginated[] = paginateBlogPosts({
-        blogPosts: listedBlogPosts,
-        blogTitle,
-        blogDescription,
-        postsPerPageOption,
-        basePageUrl: baseBlogUrl,
-        pageBasePath,
-      });
-
+      // TODO this is not the correct place to aggregate and paginate tags
+      //  for reasons similar to https://github.com/facebook/docusaurus/pull/11562
+      //  What we should do here is only read the tags file (similar to authors)
       const blogTags: BlogTags = getBlogTags({
         blogPosts,
         postsPerPageOption,
@@ -309,9 +301,10 @@ export default async function pluginContentBlog(
       });
 
       return {
+        blogTitle,
+        blogDescription,
         blogSidebarTitle,
         blogPosts,
-        blogListPaginated,
         blogTags,
         blogTagsListPath,
         authorsMap,

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

@@ -15,7 +15,7 @@ import {
   RouteBasePathSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
-import {GlobExcludeDefault} from '@docusaurus/utils';
+import {DEFAULT_PLUGIN_ID, GlobExcludeDefault} from '@docusaurus/utils';
 import type {
   PluginOptions,
   Options,
@@ -25,6 +25,7 @@ import type {
 import type {OptionValidationContext} from '@docusaurus/types';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
+  id: DEFAULT_PLUGIN_ID,
   feedOptions: {
     type: ['rss', 'atom'],
     copyright: '',

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

@@ -431,7 +431,7 @@ declare module '@docusaurus/plugin-content-blog' {
   export type PluginOptions = MDXOptions &
     TagsPluginOptions & {
       /** Plugin ID. */
-      id?: string;
+      id: string;
       /**
        * Path to the blog content directory on the file system, relative to site
        * directory.
@@ -583,9 +583,10 @@ declare module '@docusaurus/plugin-content-blog' {
   export type AuthorsMap = {[authorKey: string]: AuthorWithKey};
 
   export type BlogContent = {
-    blogSidebarTitle: string;
+    blogTitle: string; // for translation purposes
+    blogDescription: string; // for translation purposes
+    blogSidebarTitle: string; // for translation purposes
     blogPosts: BlogPost[];
-    blogListPaginated: BlogPaginated[];
     blogTags: BlogTags;
     blogTagsListPath: string;
     authorsMap?: AuthorsMap;

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

@@ -67,27 +67,24 @@ export async function buildAllRoutes({
     blogArchiveComponent,
     routeBasePath,
     archiveBasePath,
-    blogTitle,
     authorsBasePath,
     postsPerPage,
-    blogDescription,
+    pageBasePath,
   } = options;
-  const pluginId = options.id!;
+  const pluginId = options.id;
   const {createData} = actions;
   const {
+    blogTitle,
+    blogDescription,
     blogSidebarTitle,
     blogPosts,
-    blogListPaginated,
     blogTags,
     blogTagsListPath,
     authorsMap,
   } = content;
 
-  const authorsListPath = normalizeUrl([
-    baseUrl,
-    routeBasePath,
-    authorsBasePath,
-  ]);
+  const blogBasePath = normalizeUrl([baseUrl, routeBasePath]);
+  const authorsListPath = normalizeUrl([blogBasePath, authorsBasePath]);
 
   const listedBlogPosts = blogPosts.filter(shouldBeListed);
 
@@ -119,7 +116,7 @@ export async function buildAllRoutes({
 
   async function createBlogMetadataModule() {
     const blogMetadata: BlogMetadata = {
-      blogBasePath: normalizeUrl([baseUrl, routeBasePath]),
+      blogBasePath,
       blogTitle,
       authorsListPath,
     };
@@ -156,7 +153,7 @@ export async function buildAllRoutes({
     if (archiveBasePath && listedBlogPosts.length) {
       return [
         {
-          path: normalizeUrl([baseUrl, routeBasePath, archiveBasePath]),
+          path: normalizeUrl([blogBasePath, archiveBasePath]),
           component: blogArchiveComponent,
           exact: true,
           props: {
@@ -210,6 +207,15 @@ export async function buildAllRoutes({
   }
 
   function createBlogPostsPaginatedRoutes(): RouteConfig[] {
+    const blogListPaginated = paginateBlogPosts({
+      blogPosts: listedBlogPosts,
+      blogTitle,
+      blogDescription,
+      postsPerPageOption: postsPerPage,
+      basePageUrl: blogBasePath,
+      pageBasePath,
+    });
+
     return blogListPaginated.map((paginated) => {
       return {
         path: paginated.metadata.permalink,
@@ -294,12 +300,14 @@ export async function buildAllRoutes({
           sidebar: sidebarModulePath,
         },
         props: {
-          authors: authors.map((author) =>
-            toAuthorItemProp({
+          authors: authors.map((author) => {
+            const authorPosts = blogPostsByAuthorKey[author.key] ?? [];
+            const listedAuthorPosts = authorPosts.filter(shouldBeListed);
+            return toAuthorItemProp({
               author,
-              count: blogPostsByAuthorKey[author.key]?.length ?? 0,
-            }),
-          ),
+              count: listedAuthorPosts.length,
+            });
+          }),
         },
         context: {
           blogMetadata: blogMetadataModulePath,
@@ -309,16 +317,17 @@ export async function buildAllRoutes({
 
     function createAuthorPaginatedRoute(author: AuthorWithKey): RouteConfig[] {
       const authorBlogPosts = blogPostsByAuthorKey[author.key] ?? [];
+      const listedAuthorBlogPosts = authorBlogPosts.filter(shouldBeListed);
       if (!author.page) {
         return [];
       }
 
       const pages = paginateBlogPosts({
-        blogPosts: authorBlogPosts,
+        blogPosts: listedAuthorBlogPosts,
         basePageUrl: author.page.permalink,
         blogDescription,
         blogTitle,
-        pageBasePath: authorsBasePath,
+        pageBasePath,
         postsPerPageOption: postsPerPage,
       });
 
@@ -332,7 +341,10 @@ export async function buildAllRoutes({
             sidebar: sidebarModulePath,
           },
           props: {
-            author: toAuthorItemProp({author, count: authorBlogPosts.length}),
+            author: toAuthorItemProp({
+              author,
+              count: listedAuthorBlogPosts.length,
+            }),
             listMetadata: metadata,
           },
           context: {

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

@@ -5,30 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
-import type {
-  PluginOptions,
-  BlogContent,
-  BlogPaginated,
-} from '@docusaurus/plugin-content-blog';
-
-function translateListPage(
-  blogListPaginated: BlogPaginated[],
-  translations: TranslationFileContent,
-) {
-  return blogListPaginated.map((page) => {
-    const {items, metadata} = page;
-    return {
-      items,
-      metadata: {
-        ...metadata,
-        blogTitle: translations.title?.message ?? page.metadata.blogTitle,
-        blogDescription:
-          translations.description?.message ?? page.metadata.blogDescription,
-      },
-    };
-  });
-}
+import type {TranslationFile} from '@docusaurus/types';
+import type {PluginOptions, BlogContent} from '@docusaurus/plugin-content-blog';
 
 export function getTranslationFiles(options: PluginOptions): TranslationFile[] {
   return [
@@ -56,14 +34,13 @@ export function translateContent(
   content: BlogContent,
   translationFiles: TranslationFile[],
 ): BlogContent {
-  const {content: optionsTranslations} = translationFiles[0]!;
+  const {content: translations} = translationFiles[0]!;
   return {
     ...content,
+    blogTitle: translations.title?.message ?? content.blogTitle,
+    blogDescription:
+      translations.description?.message ?? content.blogDescription,
     blogSidebarTitle:
-      optionsTranslations['sidebar.title']?.message ?? content.blogSidebarTitle,
-    blogListPaginated: translateListPage(
-      content.blogListPaginated,
-      optionsTranslations,
-    ),
+      translations['sidebar.title']?.message ?? content.blogSidebarTitle,
   };
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,15 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/mdx-loader": "3.9.1",
-    "@docusaurus/module-type-aliases": "3.9.1",
-    "@docusaurus/theme-common": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/mdx-loader": "3.9.2",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap

@@ -5,27 +5,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "description": "The generated-index page title for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index title",
       },
       "sidebar.docs.doc.Second doc translatable": {
-        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "description": "The label for the doc item 'Second doc translatable' in sidebar 'docs', linking to the doc doc2",
         "message": "Second doc translatable",
       },
       "sidebar.docs.link.Link label": {
-        "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
+        "description": "The label for link 'Link label' in sidebar 'docs', linking to 'https://facebook.com'",
         "message": "Link label",
       },
       "sidebar.otherSidebar.doc.Fifth doc translatable": {
-        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {
@@ -38,27 +38,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "description": "The generated-index page title for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index title",
       },
       "sidebar.docs.doc.Second doc translatable": {
-        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "description": "The label for the doc item 'Second doc translatable' in sidebar 'docs', linking to the doc doc2",
         "message": "Second doc translatable",
       },
       "sidebar.docs.link.Link label": {
-        "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
+        "description": "The label for link 'Link label' in sidebar 'docs', linking to 'https://facebook.com'",
         "message": "Link label",
       },
       "sidebar.otherSidebar.doc.Fifth doc translatable": {
-        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {
@@ -71,27 +71,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "description": "The generated-index page title for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index title",
       },
       "sidebar.docs.doc.Second doc translatable": {
-        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "description": "The label for the doc item 'Second doc translatable' in sidebar 'docs', linking to the doc doc2",
         "message": "Second doc translatable",
       },
       "sidebar.docs.link.Link label": {
-        "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
+        "description": "The label for link 'Link label' in sidebar 'docs', linking to 'https://facebook.com'",
         "message": "Link label",
       },
       "sidebar.otherSidebar.doc.Fifth doc translatable": {
-        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {

packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts

@@ -12,8 +12,8 @@ import {
   createSlugger,
   posixPath,
   DEFAULT_PLUGIN_ID,
-  LAST_UPDATE_FALLBACK,
   getLocaleConfig,
+  TEST_VCS,
 } from '@docusaurus/utils';
 import {getTagsFile} from '@docusaurus/utils-validation';
 import {createSidebarsUtils} from '../sidebars/utils';
@@ -529,8 +529,8 @@ describe('simple site', () => {
         custom_edit_url: 'https://github.com/customUrl/docs/lorem.md',
         unrelated_front_matter: "won't be part of metadata",
       },
-      lastUpdatedAt: LAST_UPDATE_FALLBACK.lastUpdatedAt,
-      lastUpdatedBy: LAST_UPDATE_FALLBACK.lastUpdatedBy,
+      lastUpdatedAt: TEST_VCS.LAST_UPDATE_INFO.timestamp,
+      lastUpdatedBy: TEST_VCS.LAST_UPDATE_INFO.author,
       tags: [],
       unlisted: false,
     });
@@ -664,7 +664,7 @@ describe('simple site', () => {
         },
         title: 'Last Update Author Only',
       },
-      lastUpdatedAt: LAST_UPDATE_FALLBACK.lastUpdatedAt,
+      lastUpdatedAt: TEST_VCS.LAST_UPDATE_INFO.timestamp,
       lastUpdatedBy: 'Custom Author (processed by parseFrontMatter)',
       sidebarPosition: undefined,
       tags: [],

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

@@ -186,10 +186,24 @@ describe('validateDocFrontMatter slug', () => {
   });
 });
 
+describe('validateDocFrontMatter sidebar_key', () => {
+  testField({
+    prefix: 'sidebar_key',
+    validFrontMatters: [
+      {sidebar_key: undefined},
+      {sidebar_key: 'Awesome docs'},
+    ],
+    invalidFrontMatters: [[{sidebar_key: ''}, 'is not allowed to be empty']],
+  });
+});
+
 describe('validateDocFrontMatter sidebar_label', () => {
   testField({
     prefix: 'sidebar_label',
-    validFrontMatters: [{sidebar_label: 'Awesome docs'}],
+    validFrontMatters: [
+      {sidebar_label: undefined},
+      {sidebar_label: 'Awesome docs'},
+    ],
     invalidFrontMatters: [[{sidebar_label: ''}, 'is not allowed to be empty']],
   });
 });

packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts

@@ -232,35 +232,35 @@ describe('getLoadedContentTranslationFiles', () => {
           {
             "content": {
               "sidebar.sidebarWithConflicts.category.key-cat1": {
-                "description": "The label for category COMMON LABEL in sidebar sidebarWithConflicts",
+                "description": "The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.category.key-cat2": {
-                "description": "The label for category COMMON LABEL in sidebar sidebarWithConflicts",
+                "description": "The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-doc4": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-doc5": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-ref4": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-ref5": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.link.key-link1": {
-                "description": "The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com",
+                "description": "The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.link.key-link2": {
-                "description": "The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com",
+                "description": "The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com'",
                 "message": "COMMON LABEL",
               },
               "version.label": {
@@ -279,21 +279,24 @@ describe('getLoadedContentTranslationFiles', () => {
         .toThrowErrorMatchingInlineSnapshot(`
         "Multiple docs sidebar items produce the same translation key.
         - \`sidebar.sidebarWithConflicts.category.COMMON LABEL\`: 2 duplicates found:
-          - COMMON LABEL (The label for category COMMON LABEL in sidebar sidebarWithConflicts)
-          - COMMON LABEL (The label for category COMMON LABEL in sidebar sidebarWithConflicts)
+          - COMMON LABEL (The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts')
+          - COMMON LABEL (The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts')
 
         - \`sidebar.sidebarWithConflicts.link.COMMON LABEL\`: 2 duplicates found:
-          - COMMON LABEL (The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com)
-          - COMMON LABEL (The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com)
+          - COMMON LABEL (The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com')
+          - COMMON LABEL (The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com')
 
         - \`sidebar.sidebarWithConflicts.doc.COMMON LABEL\`: 4 duplicates found:
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5)
 
         To avoid translation key conflicts, use the \`key\` attribute on the sidebar items above to uniquely identify them.
-            "
+
+        When using autogenerated sidebars, you can provide a unique translation key by adding:
+        - the \`key\` attribute to category item metadata (\`_category_.json\` / \`_category_.yml\`)
+        - the \`sidebar_key\` attribute to doc item metadata (front matter in \`Category/index.mdx\`)"
       `);
     });
   });

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

@@ -568,13 +568,28 @@ describe('useSidebarBreadcrumbs', () => {
 
   it('returns first level link', () => {
     const pathname = '/somePathName';
-    const sidebar = [testCategory(), testLink({href: pathname})];
+    const sidebar = [testCategory(), testLink({href: pathname, docId: 'doc1'})];
 
     expect(createUseSidebarBreadcrumbsMock(sidebar)(pathname)).toEqual([
       sidebar[1],
     ]);
   });
 
+  it('returns doc links only', () => {
+    const pathname = '/somePathName';
+
+    // A link that is not a doc link should not appear in the breadcrumbs
+    // See https://github.com/facebook/docusaurus/pull/11616
+    const nonDocLink = testLink({href: pathname});
+    const docLink = testLink({href: pathname, docId: 'doc1'});
+
+    const sidebar = [testCategory(), nonDocLink, docLink];
+
+    expect(createUseSidebarBreadcrumbsMock(sidebar)(pathname)).toEqual([
+      docLink,
+    ]);
+  });
+
   it('returns nested category', () => {
     const pathname = '/somePathName';
 
@@ -613,7 +628,7 @@ describe('useSidebarBreadcrumbs', () => {
   it('returns nested link', () => {
     const pathname = '/somePathName';
 
-    const link = testLink({href: pathname});
+    const link = testLink({href: pathname, docId: 'docNested'});
 
     const categoryLevel3 = testCategory({
       items: [testLink(), link, testLink()],
@@ -657,6 +672,35 @@ describe('useSidebarBreadcrumbs', () => {
       createUseSidebarBreadcrumbsMock(undefined, false)('/foo'),
     ).toBeNull();
   });
+
+  // Regression test for https://github.com/facebook/docusaurus/issues/11612
+  it('returns the category that owns the URL, not a category with a link pointing to it', () => {
+    const categoryA: PropSidebarItemCategory = testCategory({
+      label: 'Category A',
+      href: '/category-a',
+      items: [
+        testLink({href: '/category-a/doc1', label: 'Doc 1'}),
+        testLink({href: '/category-a/doc2', label: 'Doc 2'}),
+        // This link points to Category B's generated-index
+        testLink({href: '/category-b', label: 'Go to Category B'}),
+      ],
+    });
+
+    const categoryB: PropSidebarItemCategory = testCategory({
+      label: 'Category B',
+      href: '/category-b',
+      items: [
+        testLink({href: '/category-b/item1', label: 'Item 1'}),
+        testLink({href: '/category-b/item2', label: 'Item 2'}),
+      ],
+    });
+
+    const sidebar: PropSidebar = [categoryA, categoryB];
+
+    expect(createUseSidebarBreadcrumbsMock(sidebar)('/category-b')).toEqual([
+      categoryB,
+    ]);
+  });
 });
 
 describe('useCurrentSidebarCategory', () => {
@@ -708,12 +752,16 @@ describe('useCurrentSidebarCategory', () => {
     expect(mockUseCurrentSidebarCategory('/cat2')).toEqual(category2);
   });
 
-  it('works for category link item', () => {
-    const link = testLink({href: '/my/link/path'});
+  it('works for category doc link item', () => {
+    const pathname = '/my/link/path';
+    const nonDocLink = testLink({href: pathname});
+    const docLink = testLink({href: pathname, docId: 'doc1'});
+
     const category: PropSidebarItemCategory = testCategory({
       href: '/cat1',
-      items: [testLink(), testLink(), link, testCategory()],
+      items: [testLink(), testLink(), nonDocLink, docLink, testCategory()],
     });
+
     const sidebar: PropSidebar = [
       testLink(),
       testLink(),
@@ -724,18 +772,28 @@ describe('useCurrentSidebarCategory', () => {
     const mockUseCurrentSidebarCategory =
       createUseCurrentSidebarCategoryMock(sidebar);
 
-    expect(mockUseCurrentSidebarCategory('/my/link/path')).toEqual(category);
+    expect(mockUseCurrentSidebarCategory(pathname)).toEqual(category);
   });
 
   it('works for nested category link item', () => {
-    const link = testLink({href: '/my/link/path'});
+    const pathname = '/my/link/path';
+    const nonDocLink = testLink({href: pathname});
+    const docLink = testLink({href: pathname, docId: 'doc1'});
+
     const category2: PropSidebarItemCategory = testCategory({
       href: '/cat2',
-      items: [testLink(), testLink(), link, testCategory()],
+      items: [
+        testLink(),
+        testLink(),
+        testCategory({items: [nonDocLink]}),
+        nonDocLink,
+        docLink,
+        testCategory(),
+      ],
     });
     const category1: PropSidebarItemCategory = testCategory({
       href: '/cat1',
-      items: [testLink(), testLink(), category2, testCategory()],
+      items: [testLink(), nonDocLink, testLink(), category2, testCategory()],
     });
     const sidebar: PropSidebar = [
       testLink(),
@@ -780,6 +838,38 @@ describe('useCurrentSidebarCategory', () => {
       `"Unexpected: cant find current sidebar in context"`,
     );
   });
+
+  // Regression test for https://github.com/facebook/docusaurus/issues/11612
+  it('returns the category that owns the URL, not a category with a link pointing to it', () => {
+    const categoryA: PropSidebarItemCategory = testCategory({
+      label: 'Category A',
+      href: '/category-a',
+      items: [
+        testLink({href: '/category-a/doc1', label: 'Doc 1'}),
+        testLink({href: '/category-a/doc2', label: 'Doc 2'}),
+        // This link points to Category B's generated-index
+        testLink({href: '/category-b', label: 'Go to Category B'}),
+      ],
+    });
+
+    const categoryB: PropSidebarItemCategory = testCategory({
+      label: 'Category B',
+      href: '/category-b',
+      items: [
+        testLink({href: '/category-b/item1', label: 'Item 1'}),
+        testLink({href: '/category-b/item2', label: 'Item 2'}),
+      ],
+    });
+
+    const sidebar: PropSidebar = [categoryA, categoryB];
+
+    const mockUseCurrentSidebarCategory =
+      createUseCurrentSidebarCategoryMock(sidebar);
+
+    // When visiting /category-b, we should get Category B (the owner),
+    // not Category A (which just has a link to it)
+    expect(mockUseCurrentSidebarCategory('/category-b')).toEqual(categoryB);
+  });
 });
 
 describe('useCurrentSidebarSiblings', () => {
@@ -805,10 +895,10 @@ describe('useCurrentSidebarSiblings', () => {
       testCategory(),
     ];
 
-    const mockUseCurrentSidebarCategory =
+    const mockUseCurrentSidebarSiblings =
       createUseCurrentSidebarSiblingsMock(sidebar);
 
-    expect(mockUseCurrentSidebarCategory('/cat')).toEqual(category.items);
+    expect(mockUseCurrentSidebarSiblings('/cat')).toEqual(category.items);
   });
 
   it('works for sidebar root', () => {
@@ -823,10 +913,10 @@ describe('useCurrentSidebarSiblings', () => {
       testCategory(),
     ];
 
-    const mockUseCurrentSidebarCategory =
+    const mockUseCurrentSidebarSiblings =
       createUseCurrentSidebarSiblingsMock(sidebar);
 
-    expect(mockUseCurrentSidebarCategory('/rootLink')).toEqual(sidebar);
+    expect(mockUseCurrentSidebarSiblings('/rootLink')).toEqual(sidebar);
   });
 
   it('works for nested sidebar category', () => {
@@ -852,10 +942,13 @@ describe('useCurrentSidebarSiblings', () => {
   });
 
   it('works for category link item', () => {
-    const link = testLink({href: '/my/link/path'});
+    const pathname = '/my/link/path';
+    const nonDocLink = testLink({href: pathname});
+    const docLink = testLink({href: pathname, docId: 'doc1'});
+
     const category: PropSidebarItemCategory = testCategory({
       href: '/cat1',
-      items: [testLink(), testLink(), link, testCategory()],
+      items: [testLink(), testLink(), nonDocLink, docLink, testCategory()],
     });
     const sidebar: PropSidebar = [
       testLink(),
@@ -864,23 +957,24 @@ describe('useCurrentSidebarSiblings', () => {
       testCategory(),
     ];
 
-    const mockUseCurrentSidebarCategory =
+    const mockUseCurrentSidebarSiblings =
       createUseCurrentSidebarSiblingsMock(sidebar);
 
-    expect(mockUseCurrentSidebarCategory('/my/link/path')).toEqual(
-      category.items,
-    );
+    expect(mockUseCurrentSidebarSiblings(pathname)).toEqual(category.items);
   });
 
   it('works for nested category link item', () => {
-    const link = testLink({href: '/my/link/path'});
+    const pathname = '/my/link/path';
+    const nonDocLink = testLink({href: pathname});
+    const docLink = testLink({href: pathname, docId: 'doc1'});
+
     const category2: PropSidebarItemCategory = testCategory({
       href: '/cat2',
-      items: [testLink(), testLink(), link, testCategory()],
+      items: [testLink(), testLink(), nonDocLink, testCategory()],
     });
     const category1: PropSidebarItemCategory = testCategory({
       href: '/cat1',
-      items: [testLink(), testLink(), category2, testCategory()],
+      items: [testLink(), testLink(), category2, docLink, testCategory()],
     });
     const sidebar: PropSidebar = [
       testLink(),
@@ -889,18 +983,16 @@ describe('useCurrentSidebarSiblings', () => {
       testCategory(),
     ];
 
-    const mockUseCurrentSidebarCategory =
+    const mockUseCurrentSidebarSiblings =
       createUseCurrentSidebarSiblingsMock(sidebar);
 
-    expect(mockUseCurrentSidebarCategory('/my/link/path')).toEqual(
-      category2.items,
-    );
+    expect(mockUseCurrentSidebarSiblings(pathname)).toEqual(category1.items);
   });
 
   it('throws when sidebar is missing', () => {
-    const mockUseCurrentSidebarCategory = createUseCurrentSidebarSiblingsMock();
+    const mockUseCurrentSidebarSiblings = createUseCurrentSidebarSiblingsMock();
     expect(() =>
-      mockUseCurrentSidebarCategory('/cat'),
+      mockUseCurrentSidebarSiblings('/cat'),
     ).toThrowErrorMatchingInlineSnapshot(
       `"Unexpected: cant find current sidebar in context"`,
     );

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

@@ -234,15 +234,22 @@ function getSidebarBreadcrumbs({
 }): PropSidebarBreadcrumbsItem[] {
   const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
 
-  function extract(items: PropSidebarItem[]) {
+  function extract(items: PropSidebarItem[]): boolean {
     for (const item of items) {
-      if (
-        (item.type === 'category' &&
-          (isSamePath(item.href, pathname) || extract(item.items))) ||
-        (item.type === 'link' && isSamePath(item.href, pathname))
+      // Extract category item
+      if (item.type === 'category') {
+        if (isSamePath(item.href, pathname) || extract(item.items)) {
+          breadcrumbs.unshift(item);
+          return true;
+        }
+      }
+      // Extract doc item
+      else if (
+        item.type === 'link' &&
+        item.docId &&
+        isSamePath(item.href, pathname)
       ) {
-        const filtered = onlyCategories && item.type !== 'category';
-        if (!filtered) {
+        if (!onlyCategories) {
           breadcrumbs.unshift(item);
         }
         return true;

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

@@ -97,6 +97,7 @@ async function doProcessDocMetadata({
     siteDir,
     siteConfig: {
       markdown: {parseFrontMatter},
+      future: {experimental_vcs: vcs},
     },
   } = context;
 
@@ -125,6 +126,7 @@ async function doProcessDocMetadata({
     filePath,
     options,
     lastUpdateFrontMatter,
+    vcs,
   );
 
   // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc

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

@@ -30,6 +30,7 @@ export const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   description: Joi.string().allow(''),
   slug: Joi.string(),
+  sidebar_key: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),

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

@@ -339,7 +339,15 @@ declare module '@docusaurus/plugin-content-docs' {
      * @see {@link DocMetadata.slug}
      */
     slug?: string;
-    /** Customizes the sidebar label for this doc. Will default to its title. */
+    /**
+     * Customizes the sidebar key for this doc,
+     * to uniquely identify it in translations.
+     */
+    sidebar_key?: string;
+    /**
+     * Customizes the sidebar label for this doc.
+     * Will default to its title.
+     */
     sidebar_label?: string;
     /**
      * Controls the position of a doc inside the generated sidebar slice when

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap

@@ -91,6 +91,7 @@ exports[`DefaultSidebarItemsGenerator generates simple flat sidebar 1`] = `
       "custom": "prop",
     },
     "id": "doc1",
+    "key": "doc1-sidebar-key",
     "label": "doc1 sidebar label",
     "type": "doc",
   },
@@ -120,6 +121,7 @@ exports[`DefaultSidebarItemsGenerator generates subfolder sidebar 1`] = `
         "type": "doc",
       },
     ],
+    "key": "doc1-sidebar-key",
     "label": "Subsubsubfolder category label",
     "link": {
       "id": "doc1",
@@ -142,6 +144,7 @@ exports[`DefaultSidebarItemsGenerator generates subfolder sidebar 1`] = `
   },
   {
     "id": "doc1",
+    "key": "doc1-sidebar-key",
     "type": "doc",
   },
   {

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts

@@ -63,6 +63,7 @@ describe('DefaultSidebarItemsGenerator', () => {
           sourceDirName: '.',
           sidebarPosition: 2,
           frontMatter: {
+            sidebar_key: 'doc1-sidebar-key',
             sidebar_label: 'doc1 sidebar label',
             sidebar_custom_props: {custom: 'prop'},
           },
@@ -254,7 +255,9 @@ describe('DefaultSidebarItemsGenerator', () => {
           sourceDirName: 'subfolder/subsubfolder',
           title: 'Subsubsubfolder category label',
           sidebarPosition: undefined,
-          frontMatter: {},
+          frontMatter: {
+            sidebar_key: 'doc1-sidebar-key',
+          },
         },
         {
           id: 'doc2',

packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts

@@ -139,6 +139,7 @@ Available doc IDs:
       const {
         sidebarPosition: position,
         frontMatter: {
+          sidebar_key: key,
           sidebar_label: label,
           sidebar_class_name: className,
           sidebar_custom_props: customProps,
@@ -151,6 +152,7 @@ Available doc IDs:
         source: fileName,
         // We don't want these fields to magically appear in the generated
         // sidebar
+        ...(key !== undefined && {key}),
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
         ...(customProps !== undefined && {customProps}),
@@ -191,6 +193,7 @@ Available doc IDs:
       function getCategoryLinkedDocMetadata():
         | {
             id: string;
+            key?: string;
             position?: number;
             label?: string;
             customProps?: {[key: string]: unknown};
@@ -212,6 +215,7 @@ Available doc IDs:
         return {
           id,
           position: doc.sidebarPosition,
+          key: doc.frontMatter.sidebar_key,
           label: doc.frontMatter.sidebar_label ?? doc.title,
           customProps: doc.frontMatter.sidebar_custom_props,
           className: doc.frontMatter.sidebar_class_name,
@@ -236,6 +240,8 @@ Available doc IDs:
         categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
 
+      const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
+
       return {
         type: 'category',
         label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
@@ -252,7 +258,7 @@ Available doc IDs:
         ...(categoryMetadata?.description && {
           description: categoryMetadata?.description,
         }),
-        ...(categoryMetadata?.key && {key: categoryMetadata?.key}),
+        ...(key && {key}),
         ...(link && {link}),
       };
     }

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

@@ -71,7 +71,16 @@ function ensureNoSidebarDuplicateEntries(
 To avoid translation key conflicts, use the ${logger.code(
       'key',
     )} attribute on the sidebar items above to uniquely identify them.
-    `);
+
+When using autogenerated sidebars, you can provide a unique translation key by adding:
+- the ${logger.code('key')} attribute to category item metadata (${logger.code(
+      '_category_.json',
+    )} / ${logger.code('_category_.yml')})
+- the ${logger.code(
+      'sidebar_key',
+    )} attribute to doc item metadata (front matter in ${logger.code(
+      'Category/index.mdx',
+    )})`);
   }
 }
 
@@ -90,7 +99,7 @@ function getSidebarTranslationFileContent(
         `sidebar.${sidebarName}.category.${categoryKey}`,
         {
           message: category.label,
-          description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+          description: `The label for category '${category.label}' in sidebar '${sidebarName}'`,
         },
       ]);
 
@@ -100,7 +109,7 @@ function getSidebarTranslationFileContent(
             `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`,
             {
               message: category.link.title,
-              description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
+              description: `The generated-index page title for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -109,7 +118,7 @@ function getSidebarTranslationFileContent(
             `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`,
             {
               message: category.link.description,
-              description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
+              description: `The generated-index page description for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -126,7 +135,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.link.${linkKey}`,
       {
         message: link.label,
-        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+        description: `The label for link '${link.label}' in sidebar '${sidebarName}', linking to '${link.href}'`,
       },
     ];
   });
@@ -140,7 +149,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.doc.${docKey}`,
       {
         message: doc.label!,
-        description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${
+        description: `The label for the doc item '${doc.label!}' in sidebar '${sidebarName}', linking to the doc ${
           doc.id
         }`,
       },

packages/docusaurus-plugin-content-docs/src/versions/__tests__/loadVersion.test.ts

@@ -8,6 +8,7 @@
 import * as path from 'path';
 import {fromPartial} from '@total-typescript/shoehorn';
 import {DEFAULT_PARSE_FRONT_MATTER} from '@docusaurus/utils/src';
+import {DEFAULT_VCS_CONFIG} from '@docusaurus/utils';
 import {readVersionsMetadata} from '../version';
 import {DEFAULT_OPTIONS} from '../../options';
 import {loadVersion} from '../loadVersion';
@@ -37,6 +38,9 @@ async function siteFixture(fixture: string) {
       markdown: {
         parseFrontMatter: DEFAULT_PARSE_FRONT_MATTER,
       },
+      future: {
+        experimental_vcs: DEFAULT_VCS_CONFIG,
+      },
     },
   });
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-pages",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Pages plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-pages.d.ts",
@@ -18,11 +18,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/mdx-loader": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/mdx-loader": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "fs-extra": "^11.1.1",
     "tslib": "^2.6.0",
     "webpack": "^5.88.1"

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

@@ -98,6 +98,7 @@ async function processPageSourceFile(
 ): Promise<Metadata | undefined> {
   const {context, options, contentPaths} = params;
   const {siteConfig, baseUrl, siteDir, i18n} = context;
+  const vcs = siteConfig.future.experimental_vcs;
   const {editUrl} = options;
 
   // Lookup in localized folder in priority
@@ -180,6 +181,7 @@ async function processPageSourceFile(
     source,
     options,
     frontMatter.last_update,
+    vcs,
   );
 
   if (isDraft({frontMatter})) {

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

@@ -13,7 +13,6 @@ import {
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
   getContentPathList,
-  DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import {createMDXLoaderRule} from '@docusaurus/mdx-loader';
 import {createAllRoutes} from './routes';
@@ -38,7 +37,7 @@ export default async function pluginContentPages(
     generatedFilesDir,
     'docusaurus-plugin-content-pages',
   );
-  const dataDir = path.join(pluginDataDirRoot, options.id ?? DEFAULT_PLUGIN_ID);
+  const dataDir = path.join(pluginDataDirRoot, options.id);
 
   async function createPagesMDXLoaderRule(): Promise<RuleSetRule> {
     const {

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

@@ -14,11 +14,12 @@ import {
   RouteBasePathSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
-import {GlobExcludeDefault} from '@docusaurus/utils';
+import {DEFAULT_PLUGIN_ID, GlobExcludeDefault} from '@docusaurus/utils';
 import type {OptionValidationContext} from '@docusaurus/types';
 import type {PluginOptions, Options} from '@docusaurus/plugin-content-pages';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
+  id: DEFAULT_PLUGIN_ID,
   path: 'src/pages', // Path to data on filesystem, relative to site dir.
   routeBasePath: '/', // URL Route.
   include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], // Extensions to include.

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

@@ -19,7 +19,7 @@ declare module '@docusaurus/plugin-content-pages' {
   };
 
   export type PluginOptions = MDXOptions & {
-    id?: string;
+    id: string;
     path: string;
     routeBasePath: string;
     include: string[];

packages/docusaurus-plugin-css-cascade-layers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-css-cascade-layers",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "CSS Cascade Layer plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,10 +18,10 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "tslib": "^2.6.0"
   },
   "engines": {

packages/docusaurus-plugin-debug/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-debug",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Debug plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-debug.d.ts",
@@ -20,9 +20,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
     "fs-extra": "^11.1.1",
     "react-json-view-lite": "^2.3.0",
     "tslib": "^2.6.0"

packages/docusaurus-plugin-google-analytics/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-google-analytics",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Global analytics (analytics.js) plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "tslib": "^2.6.0"
   },
   "peerDependencies": {

packages/docusaurus-plugin-google-gtag/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-google-gtag",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Global Site Tag (gtag.js) plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@types/gtag.js": "^0.0.12",
     "tslib": "^2.6.0"
   },

packages/docusaurus-plugin-google-tag-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-google-tag-manager",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Google Tag Manager (gtm.js) plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "tslib": "^2.6.0"
   },
   "peerDependencies": {

packages/docusaurus-plugin-ideal-image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-ideal-image",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).",
   "main": "lib/index.js",
   "types": "src/plugin-ideal-image.d.ts",
@@ -20,18 +20,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/lqip-loader": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/lqip-loader": "3.9.2",
     "@docusaurus/responsive-loader": "^1.7.0",
-    "@docusaurus/theme-translations": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/theme-translations": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "sharp": "^0.32.3",
     "tslib": "^2.6.0",
     "webpack": "^5.88.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.1",
+    "@docusaurus/module-type-aliases": "3.9.2",
     "fs-extra": "^11.1.0"
   },
   "peerDependencies": {

packages/docusaurus-plugin-pwa/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-pwa",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Docusaurus Plugin to add PWA support.",
   "main": "lib/index.js",
   "types": "src/plugin-pwa.d.ts",
@@ -22,14 +22,14 @@
   "dependencies": {
     "@babel/core": "^7.25.9",
     "@babel/preset-env": "^7.25.9",
-    "@docusaurus/bundler": "3.9.1",
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/theme-common": "3.9.1",
-    "@docusaurus/theme-translations": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/bundler": "3.9.2",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/theme-translations": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "babel-loader": "^9.2.1",
     "clsx": "^2.0.0",
     "core-js": "^3.31.1",
@@ -41,7 +41,7 @@
     "workbox-window": "^7.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.1",
+    "@docusaurus/module-type-aliases": "3.9.2",
     "fs-extra": "^11.1.0"
   },
   "peerDependencies": {

packages/docusaurus-plugin-rsdoctor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-rsdoctor",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Rsdoctor plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,9 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@rsdoctor/rspack-plugin": "^0.4.6",
     "@rsdoctor/webpack-plugin": "^0.4.6",
     "tslib": "^2.6.0"

packages/docusaurus-plugin-sitemap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-sitemap",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Simple sitemap generation plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,12 +18,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "fs-extra": "^11.1.1",
     "sitemap": "^7.1.1",
     "tslib": "^2.6.0"

packages/docusaurus-plugin-sitemap/src/__tests__/createSitemap.test.ts

@@ -6,12 +6,14 @@
  */
 
 import {fromPartial} from '@total-typescript/shoehorn';
+import {DEFAULT_VCS_CONFIG} from '@docusaurus/utils';
 import createSitemap from '../createSitemap';
 import type {PluginOptions} from '../options';
 import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
 
 const siteConfig: DocusaurusConfig = fromPartial({
   url: 'https://example.com',
+  future: {experimental_vcs: DEFAULT_VCS_CONFIG},
 });
 
 const options: PluginOptions = {

packages/docusaurus-plugin-sitemap/src/__tests__/createSitemapItem.test.ts

@@ -6,6 +6,7 @@
  */
 
 import {fromPartial} from '@total-typescript/shoehorn';
+import {TEST_VCS} from '@docusaurus/utils';
 import {createSitemapItem} from '../createSitemapItem';
 import {DEFAULT_OPTIONS} from '../options';
 import type {PluginOptions} from '../options';
@@ -13,6 +14,7 @@ import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
 
 const siteConfig: DocusaurusConfig = fromPartial({
   url: 'https://example.com',
+  future: {experimental_vcs: TEST_VCS},
 });
 
 function test(params: {

packages/docusaurus-plugin-sitemap/src/createSitemapItem.ts

@@ -6,16 +6,17 @@
  */
 
 import {applyTrailingSlash} from '@docusaurus/utils-common';
-import {getLastUpdate, normalizeUrl} from '@docusaurus/utils';
+import {normalizeUrl} from '@docusaurus/utils';
 import type {LastModOption, SitemapItem} from './types';
-import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
+import type {DocusaurusConfig, RouteConfig, VcsConfig} from '@docusaurus/types';
 import type {PluginOptions} from './options';
 
 async function getRouteLastUpdatedAt(
   route: RouteConfig,
+  vcs: Pick<VcsConfig, 'getFileLastUpdateInfo'>,
 ): Promise<number | null | undefined> {
   // Important to bail-out early here
-  // This can lead to duplicated getLastUpdate() calls and performance problems
+  // This can lead to duplicated VCS calls and performance problems
   // See https://github.com/facebook/docusaurus/pull/11211
   if (route.metadata?.lastUpdatedAt === null) {
     return null;
@@ -24,8 +25,10 @@ async function getRouteLastUpdatedAt(
     return route.metadata?.lastUpdatedAt;
   }
   if (route.metadata?.sourceFilePath) {
-    const lastUpdate = await getLastUpdate(route.metadata?.sourceFilePath);
-    return lastUpdate?.lastUpdatedAt ?? null;
+    const lastUpdateInfo = await vcs.getFileLastUpdateInfo(
+      route.metadata?.sourceFilePath,
+    );
+    return lastUpdateInfo?.timestamp ?? null;
   }
 
   return undefined;
@@ -46,14 +49,16 @@ function formatLastmod(timestamp: number, lastmodOption: LastModOption) {
 async function getRouteLastmod({
   route,
   lastmod,
+  vcs,
 }: {
   route: RouteConfig;
   lastmod: LastModOption | null;
+  vcs: Pick<VcsConfig, 'getFileLastUpdateInfo'>;
 }): Promise<string | null> {
   if (lastmod === null) {
     return null;
   }
-  const lastUpdatedAt = (await getRouteLastUpdatedAt(route)) ?? null;
+  const lastUpdatedAt = (await getRouteLastUpdatedAt(route, vcs)) ?? null;
   return lastUpdatedAt ? formatLastmod(lastUpdatedAt, lastmod) : null;
 }
 
@@ -77,6 +82,10 @@ export async function createSitemapItem({
     ]),
     changefreq,
     priority,
-    lastmod: await getRouteLastmod({route, lastmod}),
+    lastmod: await getRouteLastmod({
+      route,
+      lastmod,
+      vcs: siteConfig.future.experimental_vcs,
+    }),
   };
 }

packages/docusaurus-plugin-svgr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-svgr",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "SVGR plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,10 +18,10 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@svgr/core": "8.1.0",
     "@svgr/webpack": "^8.1.0",
     "tslib": "^2.6.0",

packages/docusaurus-plugin-vercel-analytics/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-vercel-analytics",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Global vercel analytics plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,11 +18,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@vercel/analytics": "^1.1.1",
     "tslib": "^2.6.0"
   },

packages/docusaurus-preset-classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/preset-classic",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Classic preset for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,21 +18,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/plugin-content-blog": "3.9.1",
-    "@docusaurus/plugin-content-docs": "3.9.1",
-    "@docusaurus/plugin-content-pages": "3.9.1",
-    "@docusaurus/plugin-css-cascade-layers": "3.9.1",
-    "@docusaurus/plugin-debug": "3.9.1",
-    "@docusaurus/plugin-google-analytics": "3.9.1",
-    "@docusaurus/plugin-google-gtag": "3.9.1",
-    "@docusaurus/plugin-google-tag-manager": "3.9.1",
-    "@docusaurus/plugin-sitemap": "3.9.1",
-    "@docusaurus/plugin-svgr": "3.9.1",
-    "@docusaurus/theme-classic": "3.9.1",
-    "@docusaurus/theme-common": "3.9.1",
-    "@docusaurus/theme-search-algolia": "3.9.1",
-    "@docusaurus/types": "3.9.1"
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/plugin-content-blog": "3.9.2",
+    "@docusaurus/plugin-content-docs": "3.9.2",
+    "@docusaurus/plugin-content-pages": "3.9.2",
+    "@docusaurus/plugin-css-cascade-layers": "3.9.2",
+    "@docusaurus/plugin-debug": "3.9.2",
+    "@docusaurus/plugin-google-analytics": "3.9.2",
+    "@docusaurus/plugin-google-gtag": "3.9.2",
+    "@docusaurus/plugin-google-tag-manager": "3.9.2",
+    "@docusaurus/plugin-sitemap": "3.9.2",
+    "@docusaurus/plugin-svgr": "3.9.2",
+    "@docusaurus/theme-classic": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/theme-search-algolia": "3.9.2",
+    "@docusaurus/types": "3.9.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

packages/docusaurus-remark-plugin-npm2yarn/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/remark-plugin-npm2yarn",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Remark plugin for converting npm commands to Yarn commands as tabs.",
   "main": "lib/index.js",
   "publishConfig": {

packages/docusaurus-theme-classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,19 +20,19 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/mdx-loader": "3.9.1",
-    "@docusaurus/module-type-aliases": "3.9.1",
-    "@docusaurus/plugin-content-blog": "3.9.1",
-    "@docusaurus/plugin-content-docs": "3.9.1",
-    "@docusaurus/plugin-content-pages": "3.9.1",
-    "@docusaurus/theme-common": "3.9.1",
-    "@docusaurus/theme-translations": "3.9.1",
-    "@docusaurus/types": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/mdx-loader": "3.9.2",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/plugin-content-blog": "3.9.2",
+    "@docusaurus/plugin-content-docs": "3.9.2",
+    "@docusaurus/plugin-content-pages": "3.9.2",
+    "@docusaurus/theme-common": "3.9.2",
+    "@docusaurus/theme-translations": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "@docusaurus/utils": "3.9.2",
+    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/utils-validation": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "infima": "0.2.0-alpha.45",

packages/docusaurus-theme-classic/src/theme/CodeBlock/Line/index.tsx

@@ -14,16 +14,23 @@ import styles from './styles.module.css';
 
 type Token = Props['line'][number];
 
-// Replaces '\n' by ''
-// Historical code, not sure why we even need this :/
+// This <br/ seems useful when the line has no content to prevent collapsing.
+// For code blocks with "diff" languages, this makes the empty lines collapse to
+// zero height lines, which is undesirable.
+// See also https://github.com/facebook/docusaurus/pull/11565
+function LineBreak() {
+  return <br />;
+}
+
+// Replaces single lines with '\n' by '' so that we don't end up with
+// duplicate line breaks (the '\n' + the artificial <br/> above)
+// see also https://github.com/facebook/docusaurus/pull/11565
 function fixLineBreak(line: Token[]) {
   const singleLineBreakToken =
     line.length === 1 && line[0]!.content === '\n' ? line[0] : undefined;
-
   if (singleLineBreakToken) {
     return [{...singleLineBreakToken, content: ''}];
   }
-
   return line;
 }
 
@@ -35,7 +42,6 @@ export default function CodeBlockLine({
   getTokenProps,
 }: Props): ReactNode {
   const line = fixLineBreak(lineProp);
-
   const lineProps = getLineProps({
     line,
     className: clsx(classNames, showLineNumbers && styles.codeLine),
@@ -51,7 +57,7 @@ export default function CodeBlockLine({
   });
 
   return (
-    <span {...lineProps}>
+    <div {...lineProps}>
       {showLineNumbers ? (
         <>
           <span className={styles.codeLineNumber} />
@@ -60,7 +66,7 @@ export default function CodeBlockLine({
       ) : (
         lineTokens
       )}
-      <br />
-    </span>
+      <LineBreak />
+    </div>
   );
 }

packages/docusaurus-theme-classic/src/theme/EditMetaRow/index.tsx

@@ -20,7 +20,9 @@ export default function EditMetaRow({
 }: Props): ReactNode {
   return (
     <div className={clsx('row', className)}>
-      <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
+      <div className={clsx('col', styles.noPrint)}>
+        {editUrl && <EditThisPage editUrl={editUrl} />}
+      </div>
       <div className={clsx('col', styles.lastUpdated)}>
         {(lastUpdatedAt || lastUpdatedBy) && (
           <LastUpdated