docs(website): Announce v3.2 on website/homepage (#10004)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>

.cspell.json

@@ -37,5 +37,6 @@
     "*.min.*",
     "jest/vendor"
   ],
-  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"]
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"],
+  "enableFiletypes": ["mdx"]
 }

.eslintrc.js

@@ -85,13 +85,14 @@ module.exports = {
         ignorePattern: '(eslint-disable|@)',
       },
     ],
+    'arrow-body-style': OFF,
     'no-await-in-loop': OFF,
     'no-case-declarations': WARNING,
     'no-console': OFF,
     'no-constant-binary-expression': ERROR,
     'no-continue': OFF,
     'no-control-regex': WARNING,
-    'no-else-return': [WARNING, {allowElseIf: true}],
+    'no-else-return': OFF,
     'no-empty': [WARNING, {allowEmptyCatch: true}],
     'no-lonely-if': WARNING,
     'no-nested-ternary': WARNING,
@@ -203,7 +204,10 @@ module.exports = {
       })),
     ],
     'no-template-curly-in-string': WARNING,
-    'no-unused-expressions': [WARNING, {allowTaggedTemplates: true}],
+    'no-unused-expressions': [
+      WARNING,
+      {allowTaggedTemplates: true, allowShortCircuit: true},
+    ],
     'no-useless-escape': WARNING,
     'no-void': [ERROR, {allowAsStatement: true}],
     'prefer-destructuring': WARNING,
@@ -344,10 +348,7 @@ module.exports = {
       ERROR,
       {'ts-expect-error': 'allow-with-description'},
     ],
-    '@typescript-eslint/consistent-indexed-object-style': [
-      WARNING,
-      'index-signature',
-    ],
+    '@typescript-eslint/consistent-indexed-object-style': OFF,
     '@typescript-eslint/consistent-type-imports': [
       WARNING,
       {disallowTypeAnnotations: false},

.github/workflows/argos.yml

@@ -23,14 +23,14 @@ jobs:
     # Argos is heavy to run
     # We only want to trigger Argos on PRs with the 'Argos' label
     # See https://stackoverflow.com/questions/62325286/run-github-actions-when-pull-requests-have-a-specific-label
-    if: ${{ github.ref_name == 'main' || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
+    if: ${{ (github.event_name != 'pull_request' && github.ref_name == 'main') || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: 18
 

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

@@ -24,7 +24,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn

.github/workflows/build-perf.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn
@@ -60,7 +60,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           cache: yarn
       - name: Installation

.github/workflows/canary-release.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn

.github/workflows/dependency-review.yml

@@ -15,4 +15,4 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Dependency Review
-        uses: actions/dependency-review-action@6c5ccdad469c9f8a2996bfecaec55a631a347034 # 3.1.0
+        uses: actions/dependency-review-action@733dd5d4a5203f238c33806593ec0f5fc5343d8c # 4.2.4

.github/workflows/lighthouse-report.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: 18
 
@@ -36,7 +36,7 @@ jobs:
 
       - name: Audit URLs using Lighthouse
         id: lighthouse_audit
-        uses: treosh/lighthouse-ci-action@03becbfc543944dd6e7534f7ff768abb8a296826 # 10.1.0
+        uses: treosh/lighthouse-ci-action@1b0e7c33270fbba31a18a0fbb1de7cc5256b6d39 # 11.4.0
         with:
           urls: |
             http://localhost:3000
@@ -52,7 +52,7 @@ jobs:
 
       - name: Format lighthouse score
         id: format_lighthouse_score
-        uses: actions/github-script@d7906e4ad0b1822421a7e6a35d5ca353c962f410 # v6
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # 7.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -64,7 +64,7 @@ jobs:
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@efaaab3fd41a9c3de579aba759d2552635e590fd # 2.8.0
+        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # 2.9.0
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lint-autofix.yml

@@ -0,0 +1,44 @@
+name: Lint AutoFix
+
+on:
+  pull_request:
+    branches:
+      - main
+      - docusaurus-v**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint-autofix:
+    name: Lint AutoFix
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.head_ref }}
+
+      - name: Installation
+        run: yarn
+
+      - name: AutoFix Format
+        run: yarn format
+
+      - name: AutoFix JS
+        run: yarn lint:js:fix
+
+      - name: AutoFix Style
+        run: yarn lint:style:fix
+
+      - name: AutoFix Spelling
+        run: yarn lint:spelling:fix
+
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: 'refactor: apply lint autofix'

.github/workflows/lint.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn

.github/workflows/showcase-test.yml

@@ -24,9 +24,9 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
-          node-version: '16'
+          node-version: '20'
           cache: yarn
       - name: Installation
         run: yarn

.github/workflows/tests-e2e.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
@@ -77,7 +77,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js 18
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn
@@ -131,7 +131,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js 18
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn
@@ -161,7 +161,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js 18
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn

.github/workflows/tests-swizzle.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: '18'
           cache: yarn

.github/workflows/tests-windows.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: ${{ matrix.node }}
       - name: Installation

.github/workflows/tests.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: ${{ matrix.node }}
           cache: yarn

.lintstagedrc.json

@@ -1,8 +1,5 @@
 {
   "*.{js,jsx,ts,tsx,mjs}": ["eslint --fix"],
   "*.css": ["stylelint --allow-empty-input --fix"],
-  "*": [
-    "prettier --ignore-unknown --write",
-    "cspell --no-must-find-files --no-progress"
-  ]
+  "*": ["prettier --ignore-unknown --write"]
 }

.prettierignore

@@ -24,5 +24,5 @@ website/versioned_sidebars/*.json
 examples/
 website/static/katex/katex.min.css
 
-website/changelog/_swizzle_theme_tests
+website/changelog
 website/_dogfooding/_swizzle_theme_tests

CHANGELOG.md

@@ -1,5 +1,271 @@
 # Docusaurus 2 Changelog
 
+## 3.2.0 (2024-03-29)
+
+#### :rocket: New Feature
+
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-sitemap`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#9954](https://github.com/facebook/docusaurus/pull/9954) feat(sitemap): add support for "lastmod" ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils-validation`, `docusaurus-utils`
+  - [#9912](https://github.com/facebook/docusaurus/pull/9912) feat(blog): add LastUpdateAuthor & LastUpdateTime ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-plugin-debug`, `docusaurus-types`, `docusaurus`
+  - [#9931](https://github.com/facebook/docusaurus/pull/9931) feat(core): add new plugin allContentLoaded lifecycle ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#9928](https://github.com/facebook/docusaurus/pull/9928) feat(theme-translations) Icelandic (is) ([@Hallinn](https://github.com/Hallinn))
+- `docusaurus-plugin-content-blog`
+  - [#9886](https://github.com/facebook/docusaurus/pull/9886) feat(blog): allow processing blog posts through a processBlogPosts function ([@OzakIOne](https://github.com/OzakIOne))
+  - [#9838](https://github.com/facebook/docusaurus/pull/9838) feat(blog): add blog pageBasePath plugin option ([@ilg-ul](https://github.com/ilg-ul))
+- `docusaurus`
+  - [#9681](https://github.com/facebook/docusaurus/pull/9681) feat(swizzle): ask user preferred language if no language CLI option provided ([@yixiaojiu](https://github.com/yixiaojiu))
+- `create-docusaurus`, `docusaurus-utils`
+  - [#9442](https://github.com/facebook/docusaurus/pull/9442) feat(create-docusaurus): ask user for preferred language when no language CLI option provided ([@Rafael-Martins](https://github.com/Rafael-Martins))
+- `docusaurus-plugin-vercel-analytics`
+  - [#9687](https://github.com/facebook/docusaurus/pull/9687) feat(plugin-vercel-analytics): add new vercel analytics plugin ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-mdx-loader`
+  - [#9684](https://github.com/facebook/docusaurus/pull/9684) feat(mdx-loader): the table-of-contents should display toc/headings of imported MDX partials ([@anatolykopyl](https://github.com/anatolykopyl))
+
+#### :bug: Bug Fix
+
+- `docusaurus-mdx-loader`
+  - [#9999](https://github.com/facebook/docusaurus/pull/9999) fix(mdx-loader): Ignore contentTitle coming after Markdown thematicBreak ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-search-algolia`
+  - [#9945](https://github.com/facebook/docusaurus/pull/9945) fix(a11y): move focus algolia-search focus back to search input on Escape ([@mxschmitt](https://github.com/mxschmitt))
+- `docusaurus-plugin-content-blog`
+  - [#9920](https://github.com/facebook/docusaurus/pull/9920) fix(blog): apply trailing slash to blog feed ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-theme-classic`
+  - [#9944](https://github.com/facebook/docusaurus/pull/9944) fix(theme): improve a11y of DocSidebarItemCategory expand/collapsed button ([@mxschmitt](https://github.com/mxschmitt))
+- `docusaurus-theme-translations`
+  - [#9915](https://github.com/facebook/docusaurus/pull/9915) fix(theme-translations): complete and modify Japanese translations ([@Suenaga-Ryuya](https://github.com/Suenaga-Ryuya))
+  - [#9910](https://github.com/facebook/docusaurus/pull/9910) fix(theme-translations): add Japanese translations ([@Suenaga-Ryuya](https://github.com/Suenaga-Ryuya))
+  - [#9872](https://github.com/facebook/docusaurus/pull/9872) fix(theme-translations): complete and improve Spanish theme translations ([@4troDev](https://github.com/4troDev))
+  - [#9812](https://github.com/facebook/docusaurus/pull/9812) fix(i18n): add missing theme translations for fa locale ([@VahidNaderi](https://github.com/VahidNaderi))
+- `docusaurus-utils`
+  - [#9897](https://github.com/facebook/docusaurus/pull/9897) fix(mdx-loader): mdx-code-block should support CRLF ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#9878](https://github.com/facebook/docusaurus/pull/9878) fix(core): fix default i18n calendar used, infer it from locale if possible ([@slorber](https://github.com/slorber))
+  - [#9852](https://github.com/facebook/docusaurus/pull/9852) fix(core): ensure core error boundary is able to render theme layout ([@slorber](https://github.com/slorber))
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#9861](https://github.com/facebook/docusaurus/pull/9861) fix(remark-npm2yarn): update npm-to-yarn from 2.0.0 to 2.2.1, fix pnpm extra args syntax ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-theme-classic`, `docusaurus-theme-translations`
+  - [#9851](https://github.com/facebook/docusaurus/pull/9851) fix(theme-classic): should use plurals for category items description ([@baradusov](https://github.com/baradusov))
+
+#### :running_woman: Performance
+
+- `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#9975](https://github.com/facebook/docusaurus/pull/9975) refactor(core): improve dev perf, fine-grained site reloads - part 3 ([@slorber](https://github.com/slorber))
+- `docusaurus-types`, `docusaurus`
+  - [#9968](https://github.com/facebook/docusaurus/pull/9968) refactor(core): improve dev perf, fine-grained site reloads - part2 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-types`, `docusaurus`
+  - [#9903](https://github.com/facebook/docusaurus/pull/9903) refactor(core): improve dev perf, fine-grained site reloads - part1 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-utils`
+  - [#9890](https://github.com/facebook/docusaurus/pull/9890) perf: optimize getFileCommitDate, make it async ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#9798](https://github.com/facebook/docusaurus/pull/9798) refactor(core): internalize, simplify and optimize the SSG logic ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#9868](https://github.com/facebook/docusaurus/pull/9868) refactor(theme): dates should be formatted on the client-side instead of in nodejs code ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-types`
+  - [#9669](https://github.com/facebook/docusaurus/pull/9669) refactor(theme): use JSON-LD instead of microdata for blog structured data ([@johnnyreilly](https://github.com/johnnyreilly))
+- `docusaurus-plugin-content-docs`
+  - [#9839](https://github.com/facebook/docusaurus/pull/9839) refactor(blog): improve doc global data hook error message + add doc warning to blogOnly mode ([@OzakIOne](https://github.com/OzakIOne))
+
+#### :memo: Documentation
+
+- [#9937](https://github.com/facebook/docusaurus/pull/9937) docs: use official GitHub Action to deploy to GitHub Pages ([@vlad-nestorov](https://github.com/vlad-nestorov))
+- [#9971](https://github.com/facebook/docusaurus/pull/9971) docs: replace VuePress by VitePress on tool comparison section ([@sunkanmii](https://github.com/sunkanmii))
+- [#9914](https://github.com/facebook/docusaurus/pull/9914) docs: update legacy MDX v1 links to markdown links ([@OzakIOne](https://github.com/OzakIOne))
+- [#9913](https://github.com/facebook/docusaurus/pull/9913) docs: update legacy MDX v1 links to markdown links ([@OzakIOne](https://github.com/OzakIOne))
+- [#9906](https://github.com/facebook/docusaurus/pull/9906) docs: emphasize "index slug" convention ([@Josh-Cena](https://github.com/Josh-Cena))
+- [#9877](https://github.com/facebook/docusaurus/pull/9877) docs: fix typos in deployment.mdx ([@Oreoxmt](https://github.com/Oreoxmt))
+- [#9845](https://github.com/facebook/docusaurus/pull/9845) docs: typo ([@OzakIOne](https://github.com/OzakIOne))
+- [#9816](https://github.com/facebook/docusaurus/pull/9816) docs: Add docs for Mermaid Component ([@Its-Just-Nans](https://github.com/Its-Just-Nans))
+
+#### :robot: Dependencies
+
+- [#9981](https://github.com/facebook/docusaurus/pull/9981) chore(deps): bump actions/dependency-review-action from 4.1.3 to 4.2.4 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9982](https://github.com/facebook/docusaurus/pull/9982) chore(deps): bump katex from 0.16.8 to 0.16.10 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9983](https://github.com/facebook/docusaurus/pull/9983) chore(deps): bump express from 4.18.2 to 4.19.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9977](https://github.com/facebook/docusaurus/pull/9977) chore(deps): bump webpack-dev-middleware from 5.3.3 to 5.3.4 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9958](https://github.com/facebook/docusaurus/pull/9958) chore(deps): bump follow-redirects from 1.15.4 to 1.15.6 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9892](https://github.com/facebook/docusaurus/pull/9892) chore(deps): bump actions/dependency-review-action from 4.1.2 to 4.1.3 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9869](https://github.com/facebook/docusaurus/pull/9869) chore(deps): bump actions/dependency-review-action from 4.0.0 to 4.1.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9874](https://github.com/facebook/docusaurus/pull/9874) chore(deps): bump ip from 2.0.0 to 2.0.1 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9843](https://github.com/facebook/docusaurus/pull/9843) chore(deps): bump actions/setup-node from 4.0.1 to 4.0.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9824](https://github.com/facebook/docusaurus/pull/9824) chore(deps): bump treosh/lighthouse-ci-action from 10.1.0 to 11.4.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#9823](https://github.com/facebook/docusaurus/pull/9823) chore(deps): bump marocchino/sticky-pull-request-comment from 2.8.0 to 2.9.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :wrench: Maintenance
+
+- `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-docs`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`
+  - [#9972](https://github.com/facebook/docusaurus/pull/9972) refactor(utils): remove duplicated function ([@OzakIOne](https://github.com/OzakIOne))
+- Other
+  - [#9965](https://github.com/facebook/docusaurus/pull/9965) refactor(website): organise blog posts by year ([@GingerGeek](https://github.com/GingerGeek))
+  - [#9865](https://github.com/facebook/docusaurus/pull/9865) chore(website): update @crowdin/crowdin-api-client ([@chris-bateman](https://github.com/chris-bateman))
+- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils`
+  - [#9963](https://github.com/facebook/docusaurus/pull/9963) refactor(docs,blog): last update timestamp should be in milliseconds instead of seconds ([@slorber](https://github.com/slorber))
+
+#### Committers: 22
+
+- Aolin ([@Oreoxmt](https://github.com/Oreoxmt))
+- Anatoly Kopyl ([@anatolykopyl](https://github.com/anatolykopyl))
+- Chris Bateman ([@chris-bateman](https://github.com/chris-bateman))
+- Fafowora Sunkanmi ([@sunkanmii](https://github.com/sunkanmii))
+- Hallbjörn Magnússon ([@Hallinn](https://github.com/Hallinn))
+- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Josue [4tro] A ([@4troDev](https://github.com/4troDev))
+- Liviu Ionescu ([@ilg-ul](https://github.com/ilg-ul))
+- Max Schmitt ([@mxschmitt](https://github.com/mxschmitt))
+- Rafael Martins ([@Rafael-Martins](https://github.com/Rafael-Martins))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Vahid Naderi ([@VahidNaderi](https://github.com/VahidNaderi))
+- Vlad Nestorov ([@vlad-nestorov](https://github.com/vlad-nestorov))
+- Zed Spencer-Milnes ([@GingerGeek](https://github.com/GingerGeek))
+- axel7083 ([@axel7083](https://github.com/axel7083))
+- krinza.eth ([@kaymomin](https://github.com/kaymomin))
+- n4n5 ([@Its-Just-Nans](https://github.com/Its-Just-Nans))
+- ozaki ([@OzakIOne](https://github.com/OzakIOne))
+- suenryu ([@Suenaga-Ryuya](https://github.com/Suenaga-Ryuya))
+- Нуриль Барадусов ([@baradusov](https://github.com/baradusov))
+- 翊小久 ([@yixiaojiu](https://github.com/yixiaojiu))
+
+## 3.1.1 (2024-01-26)
+
+#### :bug: Bug Fix
+
+- `docusaurus-types`, `docusaurus`
+  - [#9791](https://github.com/facebook/docusaurus/pull/9791) fix(core): broken links optimization behaves differently than non-optimized logic ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#9788](https://github.com/facebook/docusaurus/pull/9788) fix(core): links with target "\_blank" should no be checked by the broken link checker ([@slorber](https://github.com/slorber))
+  - [#9407](https://github.com/facebook/docusaurus/pull/9407) fix(core): conditionally include `hostname` parameter when using… ([@jack-robson](https://github.com/jack-robson))
+- `docusaurus-utils`
+  - [#9776](https://github.com/facebook/docusaurus/pull/9776) fix(mdx-loader): allow spaces before `mdx-code-block` info string ([@eitsupi](https://github.com/eitsupi))
+- `create-docusaurus`
+  - [#9783](https://github.com/facebook/docusaurus/pull/9783) fix(create-docusaurus): fix typo in init template sample docs ([@dawei-wang](https://github.com/dawei-wang))
+- `docusaurus-theme-common`
+  - [#9727](https://github.com/facebook/docusaurus/pull/9727) fix(theme-common): fix missing code block MagicComments style in Visual Basic (.NET) 16 ([@tats-u](https://github.com/tats-u))
+- `docusaurus-theme-classic`, `docusaurus-theme-mermaid`
+  - [#9733](https://github.com/facebook/docusaurus/pull/9733) fix: remove old useless mdx typedefs ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-utils`, `docusaurus`
+  - [#9732](https://github.com/facebook/docusaurus/pull/9732) fix(core): various broken anchor link fixes ([@slorber](https://github.com/slorber))
+
+#### :running_woman: Performance
+
+- `docusaurus`
+  - [#9778](https://github.com/facebook/docusaurus/pull/9778) perf(core): optimize broken links checker ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-classic`
+  - [#9470](https://github.com/facebook/docusaurus/pull/9470) polish(theme): MDX images should use async decoding ([@sanjaiyan-dev](https://github.com/sanjaiyan-dev))
+
+#### Committers: 6
+
+- Jack Robson ([@jack-robson](https://github.com/jack-robson))
+- Sanjaiyan Parthipan ([@sanjaiyan-dev](https://github.com/sanjaiyan-dev))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Tatsunori Uchino ([@tats-u](https://github.com/tats-u))
+- [@dawei-wang](https://github.com/dawei-wang)
+- [@eitsupi](https://github.com/eitsupi)
+
+## 3.1.0 (2024-01-05)
+
+#### :rocket: New Feature
+
+- `docusaurus-mdx-loader`, `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#9528](https://github.com/facebook/docusaurus/pull/9528) feat(core): make broken link checker detect broken anchors - add `onBrokenAnchors` config ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-mdx-loader`, `docusaurus-types`, `docusaurus`
+  - [#9674](https://github.com/facebook/docusaurus/pull/9674) feat(mdx-loader): add support for siteConfig.markdown.remarkRehypeOptions ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#9671](https://github.com/facebook/docusaurus/pull/9671) feat(theme-common): code block MagicComments support for (Visual) Basic/Batch/Fortran/COBOL/ML ([@tats-u](https://github.com/tats-u))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#9624](https://github.com/facebook/docusaurus/pull/9624) feat: siteConfig.markdown.parseFrontMatter hook ([@slorber](https://github.com/slorber))
+- `docusaurus-utils`
+  - [#9610](https://github.com/facebook/docusaurus/pull/9610) feat(core): enable port configuration via environment variable ([@OzakIOne](https://github.com/OzakIOne))
+
+#### :bug: Bug Fix
+
+- `docusaurus-theme-classic`, `docusaurus-theme-live-codeblock`
+  - [#9704](https://github.com/facebook/docusaurus/pull/9704) fix(theme): allow empty code blocks and live playgrounds ([@slorber](https://github.com/slorber))
+- `create-docusaurus`
+  - [#9696](https://github.com/facebook/docusaurus/pull/9696) fix(create-docusaurus): fix init template code blocks, and little improvements ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-pwa`
+  - [#9668](https://github.com/facebook/docusaurus/pull/9668) fix(pwa-plugin): upgrade workbox ([@SimenB](https://github.com/SimenB))
+- `docusaurus`
+  - [#9648](https://github.com/facebook/docusaurus/pull/9648) fix(cli): output help when no conventional config + no subcommand ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-live-codeblock`
+  - [#9631](https://github.com/facebook/docusaurus/pull/9631) fix(live-codeblock): stabilize react-live transformCode callback, fix editor/preview desync ([@slorber](https://github.com/slorber))
+- `docusaurus-utils`
+  - [#9617](https://github.com/facebook/docusaurus/pull/9617) fix(utils): Markdown link replacement with <> but no spaces ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-module-type-aliases`
+  - [#9612](https://github.com/facebook/docusaurus/pull/9612) fix(type-aliases): add `title` prop for imported inline SVG React components ([@axmmisaka](https://github.com/axmmisaka))
+- `docusaurus-plugin-content-blog`
+  - [#9581](https://github.com/facebook/docusaurus/pull/9581) fix(content-blog): add baseUrl for author.image_url ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-theme-translations`
+  - [#9477](https://github.com/facebook/docusaurus/pull/9477) fix(i18n): complete translations for theme-common.json Brazilian Portuguese (pt-BR) ([@c0h1b4](https://github.com/c0h1b4))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-common`
+  - [#9335](https://github.com/facebook/docusaurus/pull/9335) refactor(theme-common): allow optional desktopBreakpoint param in useWindowSize ([@jgarrow](https://github.com/jgarrow))
+
+#### :wrench: Maintenance
+
+- `docusaurus-theme-search-algolia`
+  - [#9604](https://github.com/facebook/docusaurus/pull/9604) chore: add lint autofix CI job ([@slorber](https://github.com/slorber))
+
+#### Committers: 8
+
+- Janessa Garrow ([@jgarrow](https://github.com/jgarrow))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Simen Bekkhus ([@SimenB](https://github.com/SimenB))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Tatsunori Uchino ([@tats-u](https://github.com/tats-u))
+- [@c0h1b4](https://github.com/c0h1b4)
+- axmmisaka ([@axmmisaka](https://github.com/axmmisaka))
+- ozaki ([@OzakIOne](https://github.com/OzakIOne))
+
+## 3.0.1 (2023-11-30)
+
+#### :bug: Bug Fix
+
+- `docusaurus-utils`
+  - [#9570](https://github.com/facebook/docusaurus/pull/9570) fix: add v2 retrocompatible support for quoted admonitions ([@slorber](https://github.com/slorber))
+  - [#9535](https://github.com/facebook/docusaurus/pull/9535) fix: v3 admonitions should support v2 title syntax for nested admonitions ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#9567](https://github.com/facebook/docusaurus/pull/9567) fix(theme): upgrade prism-react-renderer, fix html script and style tag highlighting ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#9531](https://github.com/facebook/docusaurus/pull/9531) fix(theme): docs html sidebar items should always be visible ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#9530](https://github.com/facebook/docusaurus/pull/9530) fix(theme): fix firefox CSS :has() support bug ([@slorber](https://github.com/slorber))
+- `create-docusaurus`
+  - [#9487](https://github.com/facebook/docusaurus/pull/9487) fix(create-docusaurus): fix readme docusaurus 2 ref ([@slorber](https://github.com/slorber))
+
+#### :robot: Dependencies
+
+- `docusaurus-plugin-debug`
+  - [#9566](https://github.com/facebook/docusaurus/pull/9566) chore(debug-plugin): migrate to a new maintained JSON Viewer ([@mcrstudio](https://github.com/mcrstudio))
+- `create-docusaurus`, `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#9572](https://github.com/facebook/docusaurus/pull/9572) chore: upgrade prism-react-renderer to 2.3.0 to avoid older clsx ([@harryzcy](https://github.com/harryzcy))
+  - [#9567](https://github.com/facebook/docusaurus/pull/9567) fix(theme): upgrade prism-react-renderer, fix html script and style tag highlighting ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`
+  - [#9464](https://github.com/facebook/docusaurus/pull/9464) chore: Upgrade clsx to 2.0.0 ([@harryzcy](https://github.com/harryzcy))
+- `docusaurus`
+  - [#9547](https://github.com/facebook/docusaurus/pull/9547) chore(core): replace `wait-on` dependency with custom lighter code ([@NickGerleman](https://github.com/NickGerleman))
+- `docusaurus-plugin-pwa`, `docusaurus`
+  - [#9529](https://github.com/facebook/docusaurus/pull/9529) chore: ugrade babel dependencies to v7.23.3 ([@reece-white](https://github.com/reece-white))
+
+#### Committers: 6
+
+- Chongyi Zheng ([@harryzcy](https://github.com/harryzcy))
+- MCR Studio ([@mcrstudio](https://github.com/mcrstudio))
+- Nick Gerleman ([@NickGerleman](https://github.com/NickGerleman))
+- Shreesh Nautiyal ([@Shreesh09](https://github.com/Shreesh09))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- [@reece-white](https://github.com/reece-white)
+
 ## 3.0.0 (2023-10-31)
 
 #### :boom: Breaking Change

README.md

@@ -1,7 +1,13 @@
-<h1 align="center">
-  <p align="center">Docusaurus</p>
-  <a href="https://docusaurus.io"><img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus"></a>
-</h1>
+<div align="center">
+  <h1 align="center">
+    Docusaurus
+    <br />
+    <br />
+    <a href="https://docusaurus.io">
+      <img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus">
+    </a>
+  </h1>
+</div>
 
 <p align="center">
   <a href="https://twitter.com/docusaurus"><img src="https://img.shields.io/twitter/follow/docusaurus.svg?style=social" align="right" alt="Twitter Follow" /></a>
@@ -14,17 +20,13 @@
   <a href= "https://github.com/prettier/prettier"><img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg"></a>
   <a href="#license"><img src="https://img.shields.io/github/license/sourcerer-io/hall-of-fame.svg?colorB=ff0000"></a>
   <a href="https://github.com/facebook/jest"><img src="https://img.shields.io/badge/tested_with-jest-99424f.svg" alt="Tested with Jest"></a>
+  <a href="https://argos-ci.com" target="_blank" rel="noreferrer noopener" aria-label="Covered by Argos"><img src="https://argos-ci.com/badge.svg" alt="Covered by Argos" width="133" height="20" /></a>
   <a href="https://gitpod.io/#https://github.com/facebook/docusaurus"><img src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" alt="Gitpod Ready-to-Code"/></a>
   <a href="https://app.netlify.com/sites/docusaurus-2/deploys"><img src="https://api.netlify.com/api/v1/badges/9e1ff559-4405-4ebe-8718-5e21c0774bc8/deploy-status" alt="Netlify Status"></a>
-  <a href="https://meercode.io/facebook/docusaurus"><img src="https://meercode.io/badge/facebook/docusaurus?type=ci-score" alt="CI Score"></a>
   <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Ffacebook%2Fdocusaurus%2Ftree%2Fmain%2Fexamples%2Fclassic&project-name=my-docusaurus-site&repo-name=my-docusaurus-site"><img src="https://vercel.com/button" alt="Deploy with Vercel"/></a>
   <a href="https://app.netlify.com/start/deploy?repository=https://github.com/slorber/docusaurus-starter"><img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify"></a>
 </p>
 
-> **We are working hard on Docusaurus v2. If you are new to Docusaurus, try using the new version instead of v1. See the [Docusaurus v2 website](https://docusaurus.io/) for more details.**
-
-> Docusaurus v1 doc is available at [v1.docusaurus.io](https://v1.docusaurus.io) and code is available on branch [docusaurus-v1](https://github.com/facebook/docusaurus/tree/docusaurus-v1)
-
 ## Introduction
 
 Docusaurus is a project for building, deploying, and maintaining open source project websites easily.

admin/new.docusaurus.io/functionUtils/playgroundUtils.ts

@@ -11,9 +11,9 @@ const CookieName = 'DocusaurusPlaygroundName';
 
 const PlaygroundConfigs = {
   codesandbox:
-    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic?file=%2FREADME.md',
+    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic?file=%2FREADME.md&privacy=public',
   'codesandbox-ts':
-    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic-typescript?file=%2FREADME.md',
+    'https://codesandbox.io/p/sandbox/github/facebook/docusaurus/tree/main/examples/classic-typescript?file=%2FREADME.md&privacy=public',
 
   // Slow to load
   // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic',

admin/new.docusaurus.io/package.json

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

admin/scripts/generateExamples.js

@@ -25,7 +25,8 @@ async function generateTemplateExample(template) {
     // Run the docusaurus script to create the template in the examples folder
     const command = template.endsWith('-typescript')
       ? template.replace('-typescript', ' -- --typescript')
-      : template;
+      : `${template} -- --javascript`;
+
     shell.exec(
       // We use the published init script on purpose, because the local init is
       // too new and could generate upcoming/unavailable config options.

admin/scripts/test-release.sh

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

argos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argos",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Argos visual diff tests",
   "license": "MIT",
   "private": true,
@@ -10,8 +10,8 @@
     "report": "playwright show-report"
   },
   "dependencies": {
-    "@argos-ci/playwright": "^1.0.1",
-    "@playwright/test": "^1.36.1",
+    "@argos-ci/playwright": "^1.9.3",
+    "@playwright/test": "^1.41.2",
     "cheerio": "^1.0.0-rc.12"
   }
 }

examples/classic-typescript/README.md

@@ -1,6 +1,6 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 

examples/classic-typescript/docs/tutorial-basics/create-a-blog-post.md

@@ -28,7 +28,7 @@ tags: [greetings]
 
 Congratulations, you have made your first post!
 
-Feel free to play around and edit this post as much you like.
+Feel free to play around and edit this post as much as you like.
 ```
 
 A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

examples/classic-typescript/docs/tutorial-basics/markdown-features.mdx

@@ -61,13 +61,13 @@ You can reference images relative to the current file as well. This is particula
 
 Markdown code blocks are supported with Syntax highlighting.
 
-    ```jsx title="src/components/HelloDocusaurus.js"
-    function HelloDocusaurus() {
-        return (
-            <h1>Hello, Docusaurus!</h1>
-        )
-    }
-    ```
+````md
+```jsx title="src/components/HelloDocusaurus.js"
+function HelloDocusaurus() {
+  return <h1>Hello, Docusaurus!</h1>;
+}
+```
+````
 
 ```jsx title="src/components/HelloDocusaurus.js"
 function HelloDocusaurus() {
@@ -79,17 +79,19 @@ function HelloDocusaurus() {
 
 Docusaurus has a special syntax to create admonitions and callouts:
 
-    :::tip My tip
+```md
+:::tip My tip
 
-    Use this awesome feature option
+Use this awesome feature option
 
-    :::
+:::
 
-    :::danger Take care
+:::danger Take care
 
-    This action is dangerous
+This action is dangerous
 
-    :::
+:::
+```
 
 :::tip My tip
 

examples/classic-typescript/package.json

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

examples/classic/README.md

@@ -1,6 +1,6 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 

examples/classic/docs/tutorial-basics/create-a-blog-post.md

@@ -28,7 +28,7 @@ tags: [greetings]
 
 Congratulations, you have made your first post!
 
-Feel free to play around and edit this post as much you like.
+Feel free to play around and edit this post as much as you like.
 ```
 
 A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

examples/classic/docs/tutorial-basics/markdown-features.mdx

@@ -61,13 +61,13 @@ You can reference images relative to the current file as well. This is particula
 
 Markdown code blocks are supported with Syntax highlighting.
 
-    ```jsx title="src/components/HelloDocusaurus.js"
-    function HelloDocusaurus() {
-        return (
-            <h1>Hello, Docusaurus!</h1>
-        )
-    }
-    ```
+````md
+```jsx title="src/components/HelloDocusaurus.js"
+function HelloDocusaurus() {
+  return <h1>Hello, Docusaurus!</h1>;
+}
+```
+````
 
 ```jsx title="src/components/HelloDocusaurus.js"
 function HelloDocusaurus() {
@@ -79,17 +79,19 @@ function HelloDocusaurus() {
 
 Docusaurus has a special syntax to create admonitions and callouts:
 
-    :::tip My tip
+```md
+:::tip My tip
 
-    Use this awesome feature option
+Use this awesome feature option
 
-    :::
+:::
 
-    :::danger Take care
+:::danger Take care
 
-    This action is dangerous
+This action is dangerous
 
-    :::
+:::
+```
 
 :::tip My tip
 

examples/classic/package.json

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

lerna.json

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

package.json

@@ -51,8 +51,11 @@
     "lint": "yarn lint:js && yarn lint:style && yarn lint:spelling",
     "lint:ci": "yarn lint:js --quiet && yarn lint:style && yarn lint:spelling",
     "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
-    "lint:spelling": "cspell \"**\" --no-progress",
+    "lint:js:fix": "yarn lint:js --fix",
+    "lint:spelling": "cspell \"**\" --no-progress --show-context --show-suggestions",
+    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | sort --ignore-case >> project-words.txt",
     "lint:style": "stylelint \"**/*.css\"",
+    "lint:style:fix": "yarn lint:style --fix",
     "lerna": "lerna",
     "test": "jest",
     "test:build:website": "./admin/scripts/test-release.sh",
@@ -80,7 +83,7 @@
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
-    "cspell": "^6.31.2",
+    "cspell": "^8.1.0",
     "eslint": "^8.45.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^8.8.0",

packages/create-docusaurus/README.md

@@ -10,6 +10,10 @@ npm init docusaurus
 yarn create docusaurus
 ```
 
+```bash
+npx create-docusaurus@latest
+```
+
 ## Usage
 
 Please see the [installation documentation](https://docusaurus.io/docs/installation).
@@ -21,7 +25,7 @@ For Docusaurus maintainers, templates can be tested with:
 ```bash
 cd `git rev-parse --show-toplevel` # Back to repo root
 rm -rf test-website
-yarn create-docusaurus test-website classic
+yarn create-docusaurus test-website classic --javascript
 cd test-website
 yarn start
 ```
@@ -33,7 +37,7 @@ Use the following to test the templates against local packages:
 ```bash
 cd `git rev-parse --show-toplevel` # Back to repo root
 rm -rf test-website-in-workspace
-yarn create-docusaurus test-website-in-workspace classic
+yarn create-docusaurus test-website-in-workspace classic --javascript
 cd test-website-in-workspace
 yarn build
 yarn start

packages/create-docusaurus/bin/index.js

@@ -38,6 +38,7 @@ program
     'Do not run package manager immediately after scaffolding',
   )
   .option('-t, --typescript', 'Use the TypeScript template variant')
+  .option('-j, --javascript', 'Use the JavaScript template variant')
   .option(
     '-g, --git-strategy <strategy>',
     `Only used if the template is a git repository.

packages/create-docusaurus/package.json

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

packages/create-docusaurus/src/index.ts

@@ -13,15 +13,29 @@ import logger from '@docusaurus/logger';
 import shell from 'shelljs';
 import prompts, {type Choice} from 'prompts';
 import supportsColor from 'supports-color';
-import {escapeShellArg} from '@docusaurus/utils';
+import {escapeShellArg, askPreferredLanguage} from '@docusaurus/utils';
 
-type CLIOptions = {
+type LanguagesOptions = {
+  javascript?: boolean;
+  typescript?: boolean;
+};
+
+type CLIOptions = LanguagesOptions & {
   packageManager?: PackageManager;
   skipInstall?: boolean;
-  typescript?: boolean;
   gitStrategy?: GitStrategy;
 };
 
+async function getLanguage(options: LanguagesOptions) {
+  if (options.typescript) {
+    return 'typescript';
+  }
+  if (options.javascript) {
+    return 'javascript';
+  }
+  return askPreferredLanguage();
+}
+
 // Only used in the rare, rare case of running globally installed create +
 // using --skip-install. We need a default name to show the tip text
 const defaultPackageManager = 'npm';
@@ -153,11 +167,14 @@ async function readTemplates(): Promise<Template[]> {
 async function copyTemplate(
   template: Template,
   dest: string,
-  typescript: boolean,
+  language: 'javascript' | 'typescript',
 ): Promise<void> {
   await fs.copy(path.join(templatesDir, 'shared'), dest);
 
-  await fs.copy(typescript ? template.tsVariantPath! : template.path, dest, {
+  const sourcePath =
+    language === 'typescript' ? template.tsVariantPath! : template.path;
+
+  await fs.copy(sourcePath, dest, {
     // Symlinks don't exist in published npm packages anymore, so this is only
     // to prevent errors during local testing
     filter: async (filePath) => !(await fs.lstat(filePath)).isSymbolicLink(),
@@ -183,6 +200,33 @@ function createTemplateChoices(templates: Template[]): Choice[] {
   ];
 }
 
+async function askTemplateChoice({
+  templates,
+  cliOptions,
+}: {
+  templates: Template[];
+  cliOptions: CLIOptions;
+}) {
+  return cliOptions.gitStrategy
+    ? 'Git repository'
+    : (
+        (await prompts(
+          {
+            type: 'select',
+            name: 'template',
+            message: 'Select a template below...',
+            choices: createTemplateChoices(templates),
+          },
+          {
+            onCancel() {
+              logger.error('A choice is required.');
+              process.exit(1);
+            },
+          },
+        )) as {template: Template | 'Git repository' | 'Local template'}
+      ).template;
+}
+
 function isValidGitRepoUrl(gitRepoUrl: string): boolean {
   return ['https://', 'git@'].some((item) => gitRepoUrl.startsWith(item));
 }
@@ -260,7 +304,7 @@ type Source =
   | {
       type: 'template';
       template: Template;
-      typescript: boolean;
+      language: 'javascript' | 'typescript';
     }
   | {
       type: 'git';
@@ -272,166 +316,193 @@ type Source =
       path: string;
     };
 
+async function createTemplateSource({
+  template,
+  cliOptions,
+}: {
+  template: Template;
+  cliOptions: CLIOptions;
+}): Promise<Source> {
+  const language = await getLanguage(cliOptions);
+  if (language === 'typescript' && !template.tsVariantPath) {
+    logger.error`Template name=${template.name} doesn't provide a TypeScript variant.`;
+    process.exit(1);
+  }
+  return {
+    type: 'template',
+    template,
+    language,
+  };
+}
+
+async function getTemplateSource({
+  templateName,
+  templates,
+  cliOptions,
+}: {
+  templateName: string;
+  templates: Template[];
+  cliOptions: CLIOptions;
+}): Promise<Source> {
+  const template = templates.find((t) => t.name === templateName);
+  if (!template) {
+    logger.error('Invalid template.');
+    process.exit(1);
+  }
+  return createTemplateSource({template, cliOptions});
+}
+
+// Get the template source explicitly requested by the user provided cli option
+async function getUserProvidedSource({
+  reqTemplate,
+  templates,
+  cliOptions,
+}: {
+  reqTemplate: string;
+  templates: Template[];
+  cliOptions: CLIOptions;
+}): Promise<Source> {
+  if (isValidGitRepoUrl(reqTemplate)) {
+    if (
+      cliOptions.gitStrategy &&
+      !gitStrategies.includes(cliOptions.gitStrategy)
+    ) {
+      logger.error`Invalid git strategy: name=${
+        cliOptions.gitStrategy
+      }. Value must be one of ${gitStrategies.join(', ')}.`;
+      process.exit(1);
+    }
+    return {
+      type: 'git',
+      url: reqTemplate,
+      strategy: cliOptions.gitStrategy ?? 'deep',
+    };
+  }
+  if (await fs.pathExists(path.resolve(reqTemplate))) {
+    return {
+      type: 'local',
+      path: path.resolve(reqTemplate),
+    };
+  }
+  return getTemplateSource({
+    templateName: reqTemplate,
+    templates,
+    cliOptions,
+  });
+}
+
+async function askGitRepositorySource({
+  cliOptions,
+}: {
+  cliOptions: CLIOptions;
+}): Promise<Source> {
+  const {gitRepoUrl} = (await prompts(
+    {
+      type: 'text',
+      name: 'gitRepoUrl',
+      validate: (url?: string) => {
+        if (url && isValidGitRepoUrl(url)) {
+          return true;
+        }
+        return logger.red('Invalid repository URL');
+      },
+      message: logger.interpolate`Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.
+(e.g: url=${'https://github.com/ownerName/repoName.git'})`,
+    },
+    {
+      onCancel() {
+        logger.error('A git repo URL is required.');
+        process.exit(1);
+      },
+    },
+  )) as {gitRepoUrl: string};
+  let strategy = cliOptions.gitStrategy;
+  if (!strategy) {
+    ({strategy} = (await prompts(
+      {
+        type: 'select',
+        name: 'strategy',
+        message: 'How should we clone this repo?',
+        choices: [
+          {title: 'Deep clone: preserve full history', value: 'deep'},
+          {title: 'Shallow clone: clone with --depth=1', value: 'shallow'},
+          {
+            title: 'Copy: do a shallow clone, but do not create a git repo',
+            value: 'copy',
+          },
+          {
+            title: 'Custom: enter your custom git clone command',
+            value: 'custom',
+          },
+        ],
+      },
+      {
+        onCancel() {
+          logger.info`Falling back to name=${'deep'}`;
+        },
+      },
+    )) as {strategy?: GitStrategy});
+  }
+  return {
+    type: 'git',
+    url: gitRepoUrl,
+    strategy: strategy ?? 'deep',
+  };
+}
+
+async function askLocalSource(): Promise<Source> {
+  const {templateDir} = (await prompts(
+    {
+      type: 'text',
+      name: 'templateDir',
+      validate: async (dir?: string) => {
+        if (dir) {
+          const fullDir = path.resolve(dir);
+          if (await fs.pathExists(fullDir)) {
+            return true;
+          }
+          return logger.red(
+            logger.interpolate`path=${fullDir} does not exist.`,
+          );
+        }
+        return logger.red('Please enter a valid path.');
+      },
+      message:
+        'Enter a local folder path, relative to the current working directory.',
+    },
+    {
+      onCancel() {
+        logger.error('A file path is required.');
+        process.exit(1);
+      },
+    },
+  )) as {templateDir: string};
+  return {
+    type: 'local',
+    path: templateDir,
+  };
+}
+
 async function getSource(
   reqTemplate: string | undefined,
   templates: Template[],
   cliOptions: CLIOptions,
 ): Promise<Source> {
   if (reqTemplate) {
-    if (isValidGitRepoUrl(reqTemplate)) {
-      if (
-        cliOptions.gitStrategy &&
-        !gitStrategies.includes(cliOptions.gitStrategy)
-      ) {
-        logger.error`Invalid git strategy: name=${
-          cliOptions.gitStrategy
-        }. Value must be one of ${gitStrategies.join(', ')}.`;
-        process.exit(1);
-      }
-      return {
-        type: 'git',
-        url: reqTemplate,
-        strategy: cliOptions.gitStrategy ?? 'deep',
-      };
-    } else if (await fs.pathExists(path.resolve(reqTemplate))) {
-      return {
-        type: 'local',
-        path: path.resolve(reqTemplate),
-      };
-    }
-    const template = templates.find((t) => t.name === reqTemplate);
-    if (!template) {
-      logger.error('Invalid template.');
-      process.exit(1);
-    }
-    if (cliOptions.typescript && !template.tsVariantPath) {
-      logger.error`Template name=${reqTemplate} doesn't provide the TypeScript variant.`;
-      process.exit(1);
-    }
-    return {
-      type: 'template',
-      template,
-      typescript: cliOptions.typescript ?? false,
-    };
+    return getUserProvidedSource({reqTemplate, templates, cliOptions});
   }
-  const template = cliOptions.gitStrategy
-    ? 'Git repository'
-    : (
-        (await prompts(
-          {
-            type: 'select',
-            name: 'template',
-            message: 'Select a template below...',
-            choices: createTemplateChoices(templates),
-          },
-          {
-            onCancel() {
-              logger.error('A choice is required.');
-              process.exit(1);
-            },
-          },
-        )) as {template: Template | 'Git repository' | 'Local template'}
-      ).template;
+
+  const template = await askTemplateChoice({templates, cliOptions});
   if (template === 'Git repository') {
-    const {gitRepoUrl} = (await prompts(
-      {
-        type: 'text',
-        name: 'gitRepoUrl',
-        validate: (url?: string) => {
-          if (url && isValidGitRepoUrl(url)) {
-            return true;
-          }
-          return logger.red('Invalid repository URL');
-        },
-        message: logger.interpolate`Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.
-(e.g: url=${'https://github.com/ownerName/repoName.git'})`,
-      },
-      {
-        onCancel() {
-          logger.error('A git repo URL is required.');
-          process.exit(1);
-        },
-      },
-    )) as {gitRepoUrl: string};
-    let strategy = cliOptions.gitStrategy;
-    if (!strategy) {
-      ({strategy} = (await prompts(
-        {
-          type: 'select',
-          name: 'strategy',
-          message: 'How should we clone this repo?',
-          choices: [
-            {title: 'Deep clone: preserve full history', value: 'deep'},
-            {title: 'Shallow clone: clone with --depth=1', value: 'shallow'},
-            {
-              title: 'Copy: do a shallow clone, but do not create a git repo',
-              value: 'copy',
-            },
-            {
-              title: 'Custom: enter your custom git clone command',
-              value: 'custom',
-            },
-          ],
-        },
-        {
-          onCancel() {
-            logger.info`Falling back to name=${'deep'}`;
-          },
-        },
-      )) as {strategy?: GitStrategy});
-    }
-    return {
-      type: 'git',
-      url: gitRepoUrl,
-      strategy: strategy ?? 'deep',
-    };
-  } else if (template === 'Local template') {
-    const {templateDir} = (await prompts(
-      {
-        type: 'text',
-        name: 'templateDir',
-        validate: async (dir?: string) => {
-          if (dir) {
-            const fullDir = path.resolve(dir);
-            if (await fs.pathExists(fullDir)) {
-              return true;
-            }
-            return logger.red(
-              logger.interpolate`path=${fullDir} does not exist.`,
-            );
-          }
-          return logger.red('Please enter a valid path.');
-        },
-        message:
-          'Enter a local folder path, relative to the current working directory.',
-      },
-      {
-        onCancel() {
-          logger.error('A file path is required.');
-          process.exit(1);
-        },
-      },
-    )) as {templateDir: string};
-    return {
-      type: 'local',
-      path: templateDir,
-    };
+    return askGitRepositorySource({cliOptions});
   }
-  let useTS = cliOptions.typescript;
-  if (!useTS && template.tsVariantPath) {
-    ({useTS} = (await prompts({
-      type: 'confirm',
-      name: 'useTS',
-      message:
-        'This template is available in TypeScript. Do you want to use the TS variant?',
-      initial: false,
-    })) as {useTS?: boolean});
+  if (template === 'Local template') {
+    return askLocalSource();
   }
-  return {
-    type: 'template',
+  return createTemplateSource({
     template,
-    typescript: useTS ?? false,
-  };
+    cliOptions,
+  });
 }
 
 async function updatePkg(pkgPath: string, obj: {[key: string]: unknown}) {
@@ -452,6 +523,7 @@ export default async function init(
     getSiteName(reqName, rootDir),
   ]);
   const dest = path.resolve(rootDir, siteName);
+
   const source = await getSource(reqTemplate, templates, cliOptions);
 
   logger.info('Creating new Docusaurus project...');
@@ -470,7 +542,7 @@ export default async function init(
     }
   } else if (source.type === 'template') {
     try {
-      await copyTemplate(source.template, dest, source.typescript);
+      await copyTemplate(source.template, dest, source.language);
     } catch (err) {
       logger.error`Copying Docusaurus template name=${source.template.name} failed!`;
       throw err;

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

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

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

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

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

@@ -1,6 +1,6 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 

packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-blog-post.md

@@ -28,7 +28,7 @@ tags: [greetings]
 
 Congratulations, you have made your first post!
 
-Feel free to play around and edit this post as much you like.
+Feel free to play around and edit this post as much as you like.
 ```
 
 A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx

@@ -61,13 +61,13 @@ You can reference images relative to the current file as well. This is particula
 
 Markdown code blocks are supported with Syntax highlighting.
 
-    ```jsx title="src/components/HelloDocusaurus.js"
-    function HelloDocusaurus() {
-        return (
-            <h1>Hello, Docusaurus!</h1>
-        )
-    }
-    ```
+````md
+```jsx title="src/components/HelloDocusaurus.js"
+function HelloDocusaurus() {
+  return <h1>Hello, Docusaurus!</h1>;
+}
+```
+````
 
 ```jsx title="src/components/HelloDocusaurus.js"
 function HelloDocusaurus() {
@@ -79,17 +79,19 @@ function HelloDocusaurus() {
 
 Docusaurus has a special syntax to create admonitions and callouts:
 
-    :::tip My tip
+```md
+:::tip My tip
 
-    Use this awesome feature option
+Use this awesome feature option
 
-    :::
+:::
 
-    :::danger Take care
+:::danger Take care
 
-    This action is dangerous
+This action is dangerous
 
-    :::
+:::
+```
 
 :::tip My tip
 

packages/docusaurus-cssnano-preset/package.json

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

packages/docusaurus-logger/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/logger",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "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.0.0",
+  "version": "3.2.0",
   "description": "Docusaurus Loader for MDX",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,11 +18,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@babel/parser": "^7.22.7",
-    "@babel/traverse": "^7.22.8",
-    "@docusaurus/logger": "3.0.0",
-    "@docusaurus/utils": "3.0.0",
-    "@docusaurus/utils-validation": "3.0.0",
+    "@docusaurus/logger": "3.2.0",
+    "@docusaurus/utils": "3.2.0",
+    "@docusaurus/utils-validation": "3.2.0",
     "@mdx-js/mdx": "^3.0.0",
     "@slorber/remark-comment": "^1.0.0",
     "escape-html": "^1.0.3",
@@ -46,7 +44,7 @@
     "webpack": "^5.88.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "3.0.0",
+    "@docusaurus/types": "3.2.0",
     "@types/escape-html": "^1.0.2",
     "@types/mdast": "^4.0.2",
     "@types/stringify-object": "^3.3.1",

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

@@ -7,7 +7,7 @@
 
 import {mdxLoader} from './loader';
 
-import type {TOCItem as TOCItemImported} from './remark/toc';
+import type {TOCItem as TOCItemImported} from './remark/toc/types';
 
 export default mdxLoader;
 

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

@@ -8,7 +8,7 @@
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
 import {
-  parseFrontMatter,
+  DEFAULT_PARSE_FRONT_MATTER,
   escapePath,
   getFileLoaderUtils,
   getWebpackLoaderCompilerName,
@@ -133,7 +133,7 @@ function extractContentTitleData(data: {
 
 export async function mdxLoader(
   this: LoaderContext<Options>,
-  fileString: string,
+  fileContent: string,
 ): Promise<void> {
   const compilerName = getWebpackLoaderCompilerName(this);
   const callback = this.async();
@@ -143,11 +143,15 @@ export async function mdxLoader(
 
   ensureMarkdownConfig(reqOptions);
 
-  const {frontMatter} = parseFrontMatter(fileString);
+  const {frontMatter} = await reqOptions.markdownConfig.parseFrontMatter({
+    filePath,
+    fileContent,
+    defaultParseFrontMatter: DEFAULT_PARSE_FRONT_MATTER,
+  });
   const mdxFrontMatter = validateMDXFrontMatter(frontMatter.mdx);
 
   const preprocessedContent = preprocessor({
-    fileContent: fileString,
+    fileContent,
     filePath,
     admonitions: reqOptions.admonitions,
     markdownConfig: reqOptions.markdownConfig,

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

@@ -165,6 +165,7 @@ async function createProcessorFactory() {
 
     const mdxProcessor = createMdxProcessor({
       ...processorOptions,
+      remarkRehypeOptions: options.markdownConfig.remarkRehypeOptions,
       format,
     });
 

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

@@ -71,6 +71,21 @@ some **markdown** *content*
       expect(result.data.contentTitle).toBeUndefined();
     });
 
+    it('ignore contentTitle if after thematic break', async () => {
+      const result = await process(`
+
+Hey
+
+---
+
+# contentTitle 1
+
+some **markdown** *content*
+  `);
+
+      expect(result.data.contentTitle).toBeUndefined();
+    });
+
     it('is able to decently serialize Markdown syntax', async () => {
       const result = await process(`
 # some **markdown** \`content\` _italic_

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

@@ -34,17 +34,24 @@ const plugin: Plugin = function plugin(
     const {toString} = await import('mdast-util-to-string');
     const {visit, EXIT} = await import('unist-util-visit');
 
-    visit(root, 'heading', (headingNode: Heading, index, parent) => {
-      if (headingNode.depth === 1) {
-        vfile.data.contentTitle = toString(headingNode);
-        if (removeContentTitle) {
-          // @ts-expect-error: TODO how to fix?
-          parent!.children.splice(index, 1);
+    visit(root, ['heading', 'thematicBreak'], (node, index, parent) => {
+      if (node.type === 'heading') {
+        const headingNode = node as Heading;
+        if (headingNode.depth === 1) {
+          vfile.data.contentTitle = toString(headingNode);
+          if (removeContentTitle) {
+            // @ts-expect-error: TODO how to fix?
+            parent!.children.splice(index, 1);
+          }
+          return EXIT; // We only handle the very first heading
+        }
+        // We only handle contentTitle if it's the very first heading found
+        if (headingNode.depth >= 1) {
+          return EXIT;
         }
-        return EXIT; // We only handle the very first heading
       }
-      // We only handle contentTitle if it's the very first heading found
-      if (headingNode.depth >= 1) {
+      // We only handle contentTitle when it's above the first thematic break
+      if (node.type === 'thematicBreak') {
         return EXIT;
       }
       return undefined;

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/SomeComponent.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default function SomeComponent() {
+  return <div>Some component</div>;
+}

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/_partial1.md

@@ -0,0 +1,7 @@
+## Partial 1
+
+Partial 1
+
+### Partial 1 Sub Heading
+
+Content

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/_partial2-nested.md

@@ -0,0 +1,3 @@
+## Partial 2 Nested
+
+Partial 2 Nested

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/_partial2.mdx

@@ -0,0 +1,11 @@
+## Partial 2
+
+Partial 2
+
+### Partial 2 Sub Heading
+
+Content
+
+import Partial2Nested from './partial2-nested.md';
+
+<Partial2Nested />

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/_partial3-unused.mdx

@@ -0,0 +1,7 @@
+## Partial 3
+
+Partial 3
+
+### Partial 3 Sub Heading
+
+Content

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/index.mdx

@@ -0,0 +1,49 @@
+import Partial1 from './_partial1.md';
+
+import SomeComponent from './SomeComponent';
+
+# Index
+
+Some text
+
+import Partial2 from './_partial2.md';
+
+## Index section 1
+
+Foo
+
+<Partial1 />
+
+Some text
+
+<SomeComponent />
+
+## Index section 2
+
+<Partial2 />
+
+## Unused partials
+
+Unused partials (that are only imported but not rendered) shouldn't alter the TOC
+
+import UnusedPartialImport from './_partial3.md';
+
+## NonExisting Partials
+
+Partials that do not exist should alter the TOC
+
+It's not the responsibility of the Remark plugin to check for their existence
+
+import DoesNotExist from './_doesNotExist.md';
+
+<DoesNotExist />
+
+## Duplicate partials
+
+It's fine if we use partials at the end
+
+<Partial1 />
+
+And we can use the partial multiple times!
+
+<Partial1 />

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__fixtures__/partials/partial-used-before-import.mdx

@@ -0,0 +1,7 @@
+# Partial used before import
+
+While it looks weird to import after usage, this remains valid MDX usage.
+
+<Partial />
+
+import Partial from './_partial.md';

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

@@ -1,238 +1,601 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`toc remark plugin does not overwrite TOC var if no TOC 1`] = `
-"foo
-
-\`bar\`
-
-\`\`\`js
-baz
-\`\`\`
-
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
 export const toc = 1;
+function _createMdxContent(props) {
+  const _components = {
+    code: "code",
+    p: "p",
+    pre: "pre",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.p, {
+      children: "foo"
+    }), "/n", _jsx(_components.p, {
+      children: _jsx(_components.code, {
+        children: "bar"
+      })
+    }), "/n", _jsx(_components.pre, {
+      children: _jsx(_components.code, {
+        className: "language-js",
+        children: "baz/n"
+      })
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin escapes inline code 1`] = `
-"export const toc = [
-	{
-		value: '<code>&lt;Head /&gt;</code>',
-		id: 'head-',
-		level: 2
-	},
-	{
-		value: '<code>&lt;Head&gt;Test&lt;/Head&gt;</code>',
-		id: 'headtesthead',
-		level: 3
-	},
-	{
-		value: '<code>&lt;div /&gt;</code>',
-		id: 'div-',
-		level: 2
-	},
-	{
-		value: '<code>&lt;div&gt; Test &lt;/div&gt;</code>',
-		id: 'div-test-div',
-		level: 2
-	},
-	{
-		value: '<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>',
-		id: 'divitestidiv',
-		level: 2
-	},
-	{
-		value: '<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>',
-		id: 'divitestidiv-1',
-		level: 2
-	}
-]
-
-## \`<Head />\`
-
-### \`<Head>Test</Head>\`
-
-## \`<div />\`
-
-## \`<div> Test </div>\`
-
-## \`<div><i>Test</i></div>\`
-
-## [\`<div><i>Test</i></div>\`](/some/link)
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+export const toc = [{
+  "value": "<code>&lt;Head /&gt;</code>",
+  "id": "head-",
+  "level": 2
+}, {
+  "value": "<code>&lt;Head&gt;Test&lt;/Head&gt;</code>",
+  "id": "headtesthead",
+  "level": 3
+}, {
+  "value": "<code>&lt;div /&gt;</code>",
+  "id": "div-",
+  "level": 2
+}, {
+  "value": "<code>&lt;div&gt; Test &lt;/div&gt;</code>",
+  "id": "div-test-div",
+  "level": 2
+}, {
+  "value": "<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>",
+  "id": "divitestidiv",
+  "level": 2
+}, {
+  "value": "<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>",
+  "id": "divitestidiv-1",
+  "level": 2
+}];
+function _createMdxContent(props) {
+  const _components = {
+    a: "a",
+    code: "code",
+    h2: "h2",
+    h3: "h3",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h2, {
+      id: "head-",
+      children: _jsx(_components.code, {
+        children: "<Head />"
+      })
+    }), "/n", _jsx(_components.h3, {
+      id: "headtesthead",
+      children: _jsx(_components.code, {
+        children: "<Head>Test</Head>"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "div-",
+      children: _jsx(_components.code, {
+        children: "<div />"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "div-test-div",
+      children: _jsx(_components.code, {
+        children: "<div> Test </div>"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "divitestidiv",
+      children: _jsx(_components.code, {
+        children: "<div><i>Test</i></div>"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "divitestidiv-1",
+      children: _jsx(_components.a, {
+        href: "/some/link",
+        children: _jsx(_components.code, {
+          children: "<div><i>Test</i></div>"
+        })
+      })
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin exports even with existing name 1`] = `
-"export const toc = [
-	{
-		value: 'Thanos',
-		id: 'thanos',
-		level: 2
-	},
-	{
-		value: 'Tony Stark',
-		id: 'tony-stark',
-		level: 2
-	},
-	{
-		value: 'Avengers',
-		id: 'avengers',
-		level: 3
-	}
-]
-
-## Thanos
-
-## Tony Stark
-
-### Avengers
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+export const toc = ['replaceMe'];
+function _createMdxContent(props) {
+  const _components = {
+    h2: "h2",
+    h3: "h3",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h2, {
+      id: "thanos",
+      children: "Thanos"
+    }), "/n", _jsx(_components.h2, {
+      id: "tony-stark",
+      children: "Tony Stark"
+    }), "/n", _jsx(_components.h3, {
+      id: "avengers",
+      children: "Avengers"
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin handles empty headings 1`] = `
-"export const toc = []
-
-# Ignore this
-
-##
-
-## ![](an-image.svg)
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+export const toc = [];
+function _createMdxContent(props) {
+  const _components = {
+    h1: "h1",
+    h2: "h2",
+    img: "img",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h1, {
+      id: "ignore-this",
+      children: "Ignore this"
+    }), "/n", _jsx(_components.h2, {
+      id: ""
+    }), "/n", _jsx(_components.h2, {
+      id: "-1",
+      children: _jsx(_components.img, {
+        src: "an-image.svg",
+        alt: ""
+      })
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin inserts below imports 1`] = `
-"import something from 'something';
-
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+import something from 'something';
 import somethingElse from 'something-else';
-
-export const toc = [
-	{
-		value: 'Title',
-		id: 'title',
-		level: 2
-	},
-	{
-		value: 'Test',
-		id: 'test',
-		level: 2
-	},
-	{
-		value: 'Again',
-		id: 'again',
-		level: 3
-	}
-]
-
-## Title
-
-## Test
-
-### Again
-
-Content.
+export const toc = [{
+  "value": "Title",
+  "id": "title",
+  "level": 2
+}, {
+  "value": "Test",
+  "id": "test",
+  "level": 2
+}, {
+  "value": "Again",
+  "id": "again",
+  "level": 3
+}];
+function _createMdxContent(props) {
+  const _components = {
+    h2: "h2",
+    h3: "h3",
+    p: "p",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h2, {
+      id: "title",
+      children: "Title"
+    }), "/n", _jsx(_components.h2, {
+      id: "test",
+      children: "Test"
+    }), "/n", _jsx(_components.h3, {
+      id: "again",
+      children: "Again"
+    }), "/n", _jsx(_components.p, {
+      children: "Content."
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin outputs empty array for no TOC 1`] = `
-"export const toc = []
-
-foo
-
-\`bar\`
-
-\`\`\`js
-baz
-\`\`\`
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+export const toc = [];
+function _createMdxContent(props) {
+  const _components = {
+    code: "code",
+    p: "p",
+    pre: "pre",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.p, {
+      children: "foo"
+    }), "/n", _jsx(_components.p, {
+      children: _jsx(_components.code, {
+        children: "bar"
+      })
+    }), "/n", _jsx(_components.pre, {
+      children: _jsx(_components.code, {
+        className: "language-js",
+        children: "baz/n"
+      })
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin works on non text phrasing content 1`] = `
-"export const toc = [
-	{
-		value: '<em>Emphasis</em>',
-		id: 'emphasis',
-		level: 2
-	},
-	{
-		value: '<strong>Importance</strong>',
-		id: 'importance',
-		level: 3
-	},
-	{
-		value: '<del>Strikethrough</del>',
-		id: 'strikethrough',
-		level: 2
-	},
-	{
-		value: '<i>HTML</i>',
-		id: 'html',
-		level: 2
-	},
-	{
-		value: '<code>inline.code()</code>',
-		id: 'inlinecode',
-		level: 2
-	},
-	{
-		value: 'some <span class="some-class">styled</span> <strong>heading</strong> <span class="myClassName &lt;&gt; weird char"></span> test',
-		id: 'some-styled-heading--test',
-		level: 2
-	}
-]
-
-## *Emphasis*
-
-### **Importance**
-
-## ~~Strikethrough~~
-
-## <i>HTML</i>
-
-## \`inline.code()\`
-
-## some <span className="some-class" style={{border: "solid"}}>styled</span> <strong>heading</strong> <span class="myClass" className="myClassName <> weird char" data-random-attr="456" /> test
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+export const toc = [{
+  "value": "<em>Emphasis</em>",
+  "id": "emphasis",
+  "level": 2
+}, {
+  "value": "<strong>Importance</strong>",
+  "id": "importance",
+  "level": 3
+}, {
+  "value": "<del>Strikethrough</del>",
+  "id": "strikethrough",
+  "level": 2
+}, {
+  "value": "<i>HTML</i>",
+  "id": "html",
+  "level": 2
+}, {
+  "value": "<code>inline.code()</code>",
+  "id": "inlinecode",
+  "level": 2
+}, {
+  "value": "some <span class=\\"some-class\\">styled</span> <strong>heading</strong> <span class=\\"myClassName &lt;&gt; weird char\\"></span> test",
+  "id": "some-styled-heading--test",
+  "level": 2
+}];
+function _createMdxContent(props) {
+  const _components = {
+    code: "code",
+    del: "del",
+    em: "em",
+    h2: "h2",
+    h3: "h3",
+    strong: "strong",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h2, {
+      id: "emphasis",
+      children: _jsx(_components.em, {
+        children: "Emphasis"
+      })
+    }), "/n", _jsx(_components.h3, {
+      id: "importance",
+      children: _jsx(_components.strong, {
+        children: "Importance"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "strikethrough",
+      children: _jsx(_components.del, {
+        children: "Strikethrough"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "html",
+      children: _jsx("i", {
+        children: "HTML"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "inlinecode",
+      children: _jsx(_components.code, {
+        children: "inline.code()"
+      })
+    }), "/n", _jsxs(_components.h2, {
+      id: "some-styled-heading--test",
+      children: ["some ", _jsx("span", {
+        className: "some-class",
+        style: {
+          border: "solid"
+        },
+        children: "styled"
+      }), " ", _jsx("strong", {
+        children: "heading"
+      }), " ", _jsx("span", {
+        class: "myClass",
+        className: "myClassName <> weird char",
+        "data-random-attr": "456"
+      }), " test"]
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;
 
 exports[`toc remark plugin works on text content 1`] = `
-"export const toc = [
-	{
-		value: 'Endi',
-		id: 'endi',
-		level: 3
-	},
-	{
-		value: 'Endi',
-		id: 'endi-1',
-		level: 2
-	},
-	{
-		value: 'Yangshun',
-		id: 'yangshun',
-		level: 3
-	},
-	{
-		value: 'I ♥ unicode.',
-		id: 'i--unicode',
-		level: 2
-	}
-]
-
-### Endi
-
-\`\`\`md
-## This is ignored
-\`\`\`
-
-## Endi
-
-Lorem ipsum
-
-### Yangshun
-
-Some content here
-
-## I ♥ unicode.
-
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
 export const c = 1;
+export const toc = [{
+  "value": "Endi",
+  "id": "endi",
+  "level": 3
+}, {
+  "value": "Endi",
+  "id": "endi-1",
+  "level": 2
+}, {
+  "value": "Yangshun",
+  "id": "yangshun",
+  "level": 3
+}, {
+  "value": "I ♥ unicode.",
+  "id": "i--unicode",
+  "level": 2
+}];
+function _createMdxContent(props) {
+  const _components = {
+    code: "code",
+    h2: "h2",
+    h3: "h3",
+    p: "p",
+    pre: "pre",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h3, {
+      id: "endi",
+      children: "Endi"
+    }), "/n", _jsx(_components.pre, {
+      children: _jsx(_components.code, {
+        className: "language-md",
+        children: "## This is ignored/n"
+      })
+    }), "/n", _jsx(_components.h2, {
+      id: "endi-1",
+      children: "Endi"
+    }), "/n", _jsx(_components.p, {
+      children: "Lorem ipsum"
+    }), "/n", _jsx(_components.h3, {
+      id: "yangshun",
+      children: "Yangshun"
+    }), "/n", _jsx(_components.p, {
+      children: "Some content here"
+    }), "/n", _jsx(_components.h2, {
+      id: "i--unicode",
+      children: "I ♥ unicode."
+    })]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
+"
+`;
+
+exports[`toc remark plugin works with imported markdown 1`] = `
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+import Partial1, {toc as __tocPartial1} from './_partial1.md';
+import SomeComponent from './SomeComponent';
+import Partial2, {toc as __tocPartial2} from './_partial2.md';
+import UnusedPartialImport from './_partial3.md';
+import DoesNotExist, {toc as __tocDoesNotExist} from './_doesNotExist.md';
+export const toc = [{
+  "value": "Index section 1",
+  "id": "index-section-1",
+  "level": 2
+}, ...__tocPartial1, {
+  "value": "Index section 2",
+  "id": "index-section-2",
+  "level": 2
+}, ...__tocPartial2, {
+  "value": "Unused partials",
+  "id": "unused-partials",
+  "level": 2
+}, {
+  "value": "NonExisting Partials",
+  "id": "nonexisting-partials",
+  "level": 2
+}, ...__tocDoesNotExist, {
+  "value": "Duplicate partials",
+  "id": "duplicate-partials",
+  "level": 2
+}, ...__tocPartial1, ...__tocPartial1];
+function _createMdxContent(props) {
+  const _components = {
+    h1: "h1",
+    h2: "h2",
+    p: "p",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h1, {
+      id: "index",
+      children: "Index"
+    }), "/n", _jsx(_components.p, {
+      children: "Some text"
+    }), "/n", "/n", _jsx(_components.h2, {
+      id: "index-section-1",
+      children: "Index section 1"
+    }), "/n", _jsx(_components.p, {
+      children: "Foo"
+    }), "/n", _jsx(Partial1, {}), "/n", _jsx(_components.p, {
+      children: "Some text"
+    }), "/n", _jsx(SomeComponent, {}), "/n", _jsx(_components.h2, {
+      id: "index-section-2",
+      children: "Index section 2"
+    }), "/n", _jsx(Partial2, {}), "/n", _jsx(_components.h2, {
+      id: "unused-partials",
+      children: "Unused partials"
+    }), "/n", _jsx(_components.p, {
+      children: "Unused partials (that are only imported but not rendered) shouldn't alter the TOC"
+    }), "/n", "/n", _jsx(_components.h2, {
+      id: "nonexisting-partials",
+      children: "NonExisting Partials"
+    }), "/n", _jsx(_components.p, {
+      children: "Partials that do not exist should alter the TOC"
+    }), "/n", _jsx(_components.p, {
+      children: "It's not the responsibility of the Remark plugin to check for their existence"
+    }), "/n", "/n", _jsx(DoesNotExist, {}), "/n", _jsx(_components.h2, {
+      id: "duplicate-partials",
+      children: "Duplicate partials"
+    }), "/n", _jsx(_components.p, {
+      children: "It's fine if we use partials at the end"
+    }), "/n", _jsx(Partial1, {}), "/n", _jsx(_components.p, {
+      children: "And we can use the partial multiple times!"
+    }), "/n", _jsx(Partial1, {})]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
+"
+`;
+
+exports[`toc remark plugin works with partial imported after its usage 1`] = `
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+import Partial, {toc as __tocPartial} from './_partial.md';
+export const toc = [...__tocPartial];
+function _createMdxContent(props) {
+  const _components = {
+    h1: "h1",
+    p: "p",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h1, {
+      id: "partial-used-before-import",
+      children: "Partial used before import"
+    }), "/n", _jsx(_components.p, {
+      children: "While it looks weird to import after usage, this remains valid MDX usage."
+    }), "/n", _jsx(Partial, {})]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
+"
+`;
+
+exports[`toc remark plugin works with partials importing other partials 1`] = `
+"import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from "react/jsx-runtime";
+import Partial2Nested, {toc as __tocPartial2Nested} from './partial2-nested.md';
+export const toc = [{
+  "value": "Partial 2",
+  "id": "partial-2",
+  "level": 2
+}, {
+  "value": "Partial 2 Sub Heading",
+  "id": "partial-2-sub-heading",
+  "level": 3
+}, ...__tocPartial2Nested];
+function _createMdxContent(props) {
+  const _components = {
+    h2: "h2",
+    h3: "h3",
+    p: "p",
+    ...props.components
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx(_components.h2, {
+      id: "partial-2",
+      children: "Partial 2"
+    }), "/n", _jsx(_components.p, {
+      children: "Partial 2"
+    }), "/n", _jsx(_components.h3, {
+      id: "partial-2-sub-heading",
+      children: "Partial 2 Sub Heading"
+    }), "/n", _jsx(_components.p, {
+      children: "Content"
+    }), "/n", "/n", _jsx(Partial2Nested, {})]
+  });
+}
+export default function MDXContent(props = {}) {
+  const {wrapper: MDXLayout} = props.components || ({});
+  return MDXLayout ? _jsx(MDXLayout, {
+    ...props,
+    children: _jsx(_createMdxContent, {
+      ...props
+    })
+  }) : _createMdxContent(props);
+}
 "
 `;

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

@@ -11,18 +11,23 @@ import plugin from '../index';
 import headings from '../../headings/index';
 
 const processFixture = async (name: string) => {
-  const {remark} = await import('remark');
   const {default: gfm} = await import('remark-gfm');
-  const {default: mdx} = await import('remark-mdx');
 
-  const filePath = path.join(__dirname, '__fixtures__', `${name}.md`);
+  const {compile} = await import('@mdx-js/mdx');
+
+  const filePath = path.join(
+    __dirname,
+    '__fixtures__',
+    name.endsWith('.mdx') ? name : `${name}.md`,
+  );
+
   const file = await vfile.read(filePath);
-  const result = await remark()
-    .use(headings)
-    .use(gfm)
-    .use(mdx)
-    .use(plugin)
-    .process(file);
+
+  const result = await compile(file, {
+    format: 'mdx',
+    remarkPlugins: [headings, gfm, plugin],
+    rehypePlugins: [],
+  });
 
   return result.value;
 };
@@ -70,4 +75,21 @@ describe('toc remark plugin', () => {
     const result = await processFixture('empty-headings');
     expect(result).toMatchSnapshot();
   });
+
+  it('works with imported markdown', async () => {
+    const result = await processFixture('partials/index.mdx');
+    expect(result).toMatchSnapshot();
+  });
+
+  it('works with partials importing other partials', async () => {
+    const result = await processFixture('partials/_partial2.mdx');
+    expect(result).toMatchSnapshot();
+  });
+
+  it('works with partial imported after its usage', async () => {
+    const result = await processFixture(
+      'partials/partial-used-before-import.mdx',
+    );
+    expect(result).toMatchSnapshot();
+  });
 });

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

@@ -5,154 +5,183 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {parse, type ParserOptions} from '@babel/parser';
-import traverse from '@babel/traverse';
-import stringifyObject from 'stringify-object';
-import {toValue} from '../utils';
-import type {Identifier} from '@babel/types';
-import type {Node, Parent} from 'unist';
-import type {Heading, Literal} from 'mdast';
+import {
+  addTocSliceImportIfNeeded,
+  createTOCExportNodeAST,
+  findDefaultImportName,
+  getImportDeclarations,
+  isMarkdownImport,
+  isNamedExport,
+} from './utils';
+import type {Heading, Root} from 'mdast';
 // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import type {Transformer} from 'unified';
 import type {
   MdxjsEsm,
+  MdxJsxFlowElement,
   // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 } from 'mdast-util-mdx';
-
-// TODO as of April 2023, no way to import/re-export this ESM type easily :/
-// TODO upgrade to TS 5.3
-// See https://github.com/microsoft/TypeScript/issues/49721#issuecomment-1517839391
-// import type {Plugin} from 'unified';
-type Plugin = any; // TODO fix this asap
-
-export type TOCItem = {
-  readonly value: string;
-  readonly id: string;
-  readonly level: number;
-};
-
-const parseOptions: ParserOptions = {
-  plugins: ['jsx'],
-  sourceType: 'module',
-};
-
-const isImport = (child: any): child is Literal =>
-  child.type === 'mdxjsEsm' && child.value.startsWith('import');
-const hasImports = (index: number) => index > -1;
-const isExport = (child: any): child is Literal =>
-  child.type === 'mdxjsEsm' && child.value.startsWith('export');
+import type {TOCItems} from './types';
+import type {ImportDeclaration} from 'estree';
 
 interface PluginOptions {
   name?: string;
 }
 
-const isTarget = (child: Literal, name: string) => {
-  let found = false;
-  const ast = parse(child.value, parseOptions);
-  traverse(ast, {
-    VariableDeclarator: (path) => {
-      if ((path.node.id as Identifier).name === name) {
-        found = true;
-      }
-    },
-  });
-  return found;
-};
+// ComponentName (default export) => ImportDeclaration mapping
+type MarkdownImports = Map<string, {declaration: ImportDeclaration}>;
 
-const getOrCreateExistingTargetIndex = async (
-  children: Node[],
-  name: string,
-) => {
-  let importsIndex = -1;
-  let targetIndex = -1;
+// MdxjsEsm node representing an already existing "export const toc" declaration
+type ExistingTOCExport = MdxjsEsm | null;
 
-  children.forEach((child, index) => {
-    if (isImport(child)) {
-      importsIndex = index;
-    } else if (isExport(child) && isTarget(child, name)) {
-      targetIndex = index;
+function createTocSliceImportName({
+  tocExportName,
+  componentName,
+}: {
+  tocExportName: string;
+  componentName: string;
+}) {
+  // The name of the toc slice import alias doesn't matter much
+  // We just need to ensure it's valid and won't conflict with other names
+  return `__${tocExportName}${componentName}`;
+}
+
+async function collectImportsExports({
+  root,
+  tocExportName,
+}: {
+  root: Root;
+  tocExportName: string;
+}): Promise<{
+  markdownImports: MarkdownImports;
+  existingTocExport: ExistingTOCExport;
+}> {
+  const {visit} = await import('unist-util-visit');
+
+  const markdownImports = new Map<string, {declaration: ImportDeclaration}>();
+  let existingTocExport: MdxjsEsm | null = null;
+
+  visit(root, 'mdxjsEsm', (node) => {
+    if (!node.data?.estree) {
+      return;
+    }
+    if (isNamedExport(node, tocExportName)) {
+      existingTocExport = node;
     }
-  });
 
-  if (targetIndex === -1) {
-    const target = await createExportNode(name, []);
-
-    targetIndex = hasImports(importsIndex) ? importsIndex + 1 : 0;
-    children.splice(targetIndex, 0, target);
-  }
-
-  return targetIndex;
-};
-
-const plugin: Plugin = function plugin(
-  options: PluginOptions = {},
-): Transformer {
-  const name = options.name || 'toc';
-
-  return async (root) => {
-    const {toString} = await import('mdast-util-to-string');
-    const {visit} = await import('unist-util-visit');
-
-    const headings: TOCItem[] = [];
-
-    visit(root, 'heading', (child: Heading) => {
-      const value = toString(child);
-
-      // depth:1 headings are titles and not included in the TOC
-      if (!value || child.depth < 2) {
+    getImportDeclarations(node.data.estree).forEach((declaration) => {
+      if (!isMarkdownImport(declaration)) {
         return;
       }
-
-      headings.push({
-        value: toValue(child, toString),
-        id: child.data!.id!,
-        level: child.depth,
+      const componentName = findDefaultImportName(declaration);
+      if (!componentName) {
+        return;
+      }
+      markdownImports.set(componentName, {
+        declaration,
       });
     });
+  });
 
-    const {children} = root as Parent;
-    const targetIndex = await getOrCreateExistingTargetIndex(children, name);
+  return {markdownImports, existingTocExport};
+}
 
-    if (headings?.length) {
-      children[targetIndex] = await createExportNode(name, headings);
+async function collectTOCItems({
+  root,
+  tocExportName,
+  markdownImports,
+}: {
+  root: Root;
+  tocExportName: string;
+  markdownImports: MarkdownImports;
+}): Promise<{
+  // The toc items we collected in the tree
+  tocItems: TOCItems;
+}> {
+  const {toString} = await import('mdast-util-to-string');
+  const {visit} = await import('unist-util-visit');
+
+  const tocItems: TOCItems = [];
+
+  visit(root, (child) => {
+    if (child.type === 'heading') {
+      visitHeading(child);
+    } else if (child.type === 'mdxJsxFlowElement') {
+      visitJSXElement(child);
     }
-  };
-};
+  });
 
-export default plugin;
+  return {tocItems};
 
-async function createExportNode(name: string, object: any): Promise<MdxjsEsm> {
-  const {valueToEstree} = await import('estree-util-value-to-estree');
+  // Visit Markdown headings
+  function visitHeading(node: Heading) {
+    const value = toString(node);
+    // depth:1 headings are titles and not included in the TOC
+    if (!value || node.depth < 2) {
+      return;
+    }
+    tocItems.push({
+      type: 'heading',
+      heading: node,
+    });
+  }
 
-  return {
-    type: 'mdxjsEsm',
-    value: `export const ${name} = ${stringifyObject(object)}`,
-    data: {
-      estree: {
-        type: 'Program',
-        body: [
-          {
-            type: 'ExportNamedDeclaration',
-            declaration: {
-              type: 'VariableDeclaration',
-              declarations: [
-                {
-                  type: 'VariableDeclarator',
-                  id: {
-                    type: 'Identifier',
-                    name,
-                  },
-                  init: valueToEstree(object),
-                },
-              ],
-              kind: 'const',
-            },
-            specifiers: [],
-            source: null,
-          },
-        ],
-        sourceType: 'module',
-      },
-    },
+  // Visit JSX elements, such as <Partial/>
+  function visitJSXElement(node: MdxJsxFlowElement) {
+    const componentName = node.name;
+    if (!componentName) {
+      return;
+    }
+    const importDeclaration = markdownImports.get(componentName)?.declaration;
+    if (!importDeclaration) {
+      return;
+    }
+
+    const tocSliceImportName = createTocSliceImportName({
+      tocExportName,
+      componentName,
+    });
+
+    tocItems.push({
+      type: 'slice',
+      importName: tocSliceImportName,
+    });
+
+    addTocSliceImportIfNeeded({
+      importDeclaration,
+      tocExportName,
+      tocSliceImportName,
+    });
+  }
+}
+
+export default function plugin(options: PluginOptions = {}): Transformer<Root> {
+  const tocExportName = options.name || 'toc';
+
+  return async (root) => {
+    const {markdownImports, existingTocExport} = await collectImportsExports({
+      root,
+      tocExportName,
+    });
+
+    // If user explicitly writes "export const toc" in his mdx file
+    // We keep it as is do not override their explicit toc structure
+    // See https://github.com/facebook/docusaurus/pull/7530#discussion_r1458087876
+    if (existingTocExport) {
+      return;
+    }
+
+    const {tocItems} = await collectTOCItems({
+      root,
+      tocExportName,
+      markdownImports,
+    });
+
+    root.children.push(
+      await createTOCExportNodeAST({
+        tocExportName,
+        tocItems,
+      }),
+    );
   };
 }

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

@@ -0,0 +1,29 @@
+/**
+ * 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 type {Heading} from 'mdast';
+
+// Note: this type is exported from mdx-loader and used in theme
+// Need to keep it retro compatible
+export type TOCItem = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+};
+
+export type TOCHeading = {
+  readonly type: 'heading';
+  readonly heading: Heading;
+};
+
+// A TOC slice represents a TOCItem[] imported from a partial
+export type TOCSlice = {
+  readonly type: 'slice';
+  readonly importName: string;
+};
+
+export type TOCItems = (TOCHeading | TOCSlice)[];

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

@@ -0,0 +1,177 @@
+/**
+ * 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 {toValue} from '../utils';
+import type {Node} from 'unist';
+import type {
+  MdxjsEsm,
+  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+} from 'mdast-util-mdx';
+import type {TOCHeading, TOCItem, TOCItems, TOCSlice} from './types';
+import type {
+  Program,
+  SpreadElement,
+  ImportDeclaration,
+  ImportSpecifier,
+} from 'estree';
+
+export function getImportDeclarations(program: Program): ImportDeclaration[] {
+  return program.body.filter(
+    (item): item is ImportDeclaration => item.type === 'ImportDeclaration',
+  );
+}
+
+export function isMarkdownImport(node: Node): node is ImportDeclaration {
+  if (node.type !== 'ImportDeclaration') {
+    return false;
+  }
+  const importPath = (node as ImportDeclaration).source.value;
+  return typeof importPath === 'string' && /\.mdx?$/.test(importPath);
+}
+
+export function findDefaultImportName(
+  importDeclaration: ImportDeclaration,
+): string | undefined {
+  return importDeclaration.specifiers.find(
+    (o: Node) => o.type === 'ImportDefaultSpecifier',
+  )?.local.name;
+}
+
+export function findNamedImportSpecifier(
+  importDeclaration: ImportDeclaration,
+  localName: string,
+): ImportSpecifier | undefined {
+  return importDeclaration?.specifiers.find(
+    (specifier): specifier is ImportSpecifier =>
+      specifier.type === 'ImportSpecifier' &&
+      specifier.local.name === localName,
+  );
+}
+
+// Before: import Partial from "partial"
+// After: import Partial, {toc as __tocPartial} from "partial"
+export function addTocSliceImportIfNeeded({
+  importDeclaration,
+  tocExportName,
+  tocSliceImportName,
+}: {
+  importDeclaration: ImportDeclaration;
+  tocExportName: string;
+  tocSliceImportName: string;
+}): void {
+  // We only add the toc slice named import if it doesn't exist already
+  if (!findNamedImportSpecifier(importDeclaration, tocSliceImportName)) {
+    importDeclaration.specifiers.push({
+      type: 'ImportSpecifier',
+      imported: {type: 'Identifier', name: tocExportName},
+      local: {type: 'Identifier', name: tocSliceImportName},
+    });
+  }
+}
+
+export function isNamedExport(
+  node: Node,
+  exportName: string,
+): node is MdxjsEsm {
+  if (node.type !== 'mdxjsEsm') {
+    return false;
+  }
+  const program = (node as MdxjsEsm).data?.estree;
+  if (!program) {
+    return false;
+  }
+  if (program.body.length !== 1) {
+    return false;
+  }
+  const exportDeclaration = program.body[0]!;
+  if (exportDeclaration.type !== 'ExportNamedDeclaration') {
+    return false;
+  }
+  const variableDeclaration = exportDeclaration.declaration;
+  if (variableDeclaration?.type !== 'VariableDeclaration') {
+    return false;
+  }
+  const {id} = variableDeclaration.declarations[0]!;
+  if (id.type !== 'Identifier') {
+    return false;
+  }
+
+  return id.name === exportName;
+}
+
+export async function createTOCExportNodeAST({
+  tocExportName,
+  tocItems,
+}: {
+  tocExportName: string;
+  tocItems: TOCItems;
+}): Promise<MdxjsEsm> {
+  function createTOCSliceAST(tocSlice: TOCSlice): SpreadElement {
+    return {
+      type: 'SpreadElement',
+      argument: {type: 'Identifier', name: tocSlice.importName},
+    };
+  }
+
+  async function createTOCHeadingAST({heading}: TOCHeading) {
+    const {toString} = await import('mdast-util-to-string');
+    const {valueToEstree} = await import('estree-util-value-to-estree');
+    const value: TOCItem = {
+      value: toValue(heading, toString),
+      id: heading.data!.id!,
+      level: heading.depth,
+    };
+    return valueToEstree(value);
+  }
+
+  async function createTOCItemAST(tocItem: TOCItems[number]) {
+    switch (tocItem.type) {
+      case 'slice':
+        return createTOCSliceAST(tocItem);
+      case 'heading':
+        return createTOCHeadingAST(tocItem);
+      default: {
+        throw new Error(`unexpected toc item type`);
+      }
+    }
+  }
+
+  return {
+    type: 'mdxjsEsm',
+    value: '', // See https://github.com/facebook/docusaurus/pull/9684#discussion_r1457595181
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExportNamedDeclaration',
+            declaration: {
+              type: 'VariableDeclaration',
+              declarations: [
+                {
+                  type: 'VariableDeclarator',
+                  id: {
+                    type: 'Identifier',
+                    name: tocExportName,
+                  },
+                  init: {
+                    type: 'ArrayExpression',
+                    elements: await Promise.all(tocItems.map(createTOCItemAST)),
+                  },
+                },
+              ],
+              kind: 'const',
+            },
+            specifiers: [],
+            source: null,
+          },
+        ],
+        sourceType: 'module',
+      },
+    },
+  };
+}

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

@@ -12,17 +12,17 @@ exports[`transformAsset plugin pathname protocol 1`] = `
 exports[`transformAsset plugin transform md links to <a /> 1`] = `
 "[asset](https://example.com/asset.pdf)
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} />
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} />
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-in paragraph <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+in paragraph <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset (2).pdf").default}>asset with URL encoded chars</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset (2).pdf").default}>asset with URL encoded chars</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default + '#page=2'}>asset with hash</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default + '#page=2'}>asset with hash</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} title="Title">asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} title="Title">asset</a>
 
 [page](noUrl.md)
 
@@ -36,24 +36,24 @@ in paragraph <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file
 
 [assets](/github/!file-loader!/assets.pdf)
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static2/asset2.pdf").default}>asset2</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static2/asset2.pdf").default}>asset2</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>@site/static/staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>@site/static/staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default + '#page=2'} title="Title">@site/static/staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default + '#page=2'} title="Title">@site/static/staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>Just staticAsset.pdf</a>, and <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>**awesome** staticAsset 2.pdf 'It is really "AWESOME"'</a>, but also <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>coded \`staticAsset 3.pdf\`</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>Just staticAsset.pdf</a>, and <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>**awesome** staticAsset 2.pdf 'It is really "AWESOME"'</a>, but also <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>coded \`staticAsset 3.pdf\`</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAssetImage.png").default}><img alt="Clickable Docusaurus logo" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/staticAssetImage.png").default} width="200" height="200" /></a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAssetImage.png").default}><img alt="Clickable Docusaurus logo" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/staticAssetImage.png").default} width="200" height="200" /></a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}><span style={{color: "red"}}>Stylized link to asset file</span></a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}><span style={{color: "red"}}>Stylized link to asset file</span></a>
 
-<a target="_blank" href={require("./data.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json").default}>JSON</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("./data.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json").default}>JSON</a>
 
-<a target="_blank" href={require("./static/static-json.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json").default}>static JSON</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("./static/static-json.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json").default}>static JSON</a>
 "
 `;

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

@@ -73,6 +73,34 @@ async function toAssetRequireNode(
     value: '_blank',
   });
 
+  // Assets are not routes, and are required by Webpack already
+  // They should not trigger the broken link checker
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'data-noBrokenLinkCheck',
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: 'true',
+      data: {
+        estree: {
+          type: 'Program',
+          body: [
+            {
+              type: 'ExpressionStatement',
+              expression: {
+                type: 'Literal',
+                value: true,
+                raw: 'true',
+              },
+            },
+          ],
+          sourceType: 'module',
+          comments: [],
+        },
+      },
+    },
+  });
+
   attributes.push({
     type: 'mdxJsxAttribute',
     name: 'href',

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

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/module-type-aliases",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Docusaurus module type aliases.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/types": "3.0.0",
+    "@docusaurus/types": "3.2.0",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",

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

@@ -260,6 +260,15 @@ declare module '@docusaurus/useRouteContext' {
   export default function useRouteContext(): PluginRouteContext;
 }
 
+declare module '@docusaurus/useBrokenLinks' {
+  export type BrokenLinks = {
+    collectLink: (link: string | undefined) => void;
+    collectAnchor: (anchor: string | undefined) => void;
+  };
+
+  export default function useBrokenLinks(): BrokenLinks;
+}
+
 declare module '@docusaurus/useIsBrowser' {
   export default function useIsBrowser(): boolean;
 }
@@ -356,7 +365,9 @@ declare module '@docusaurus/useGlobalData' {
 declare module '*.svg' {
   import type {ComponentType, SVGProps} from 'react';
 
-  const ReactComponent: ComponentType<SVGProps<SVGSVGElement>>;
+  const ReactComponent: ComponentType<
+    SVGProps<SVGSVGElement> & {title?: string}
+  >;
 
   export default ReactComponent;
 }

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

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

packages/docusaurus-plugin-client-redirects/src/__tests__/collectRedirects.test.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {removeTrailingSlash} from '@docusaurus/utils';
+import {removeTrailingSlash} from '@docusaurus/utils-common';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
 import collectRedirects from '../collectRedirects';
 import {validateOptions} from '../options';

packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts

@@ -7,8 +7,11 @@
 
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import {addTrailingSlash, removeTrailingSlash} from '@docusaurus/utils';
-import {applyTrailingSlash} from '@docusaurus/utils-common';
+import {
+  applyTrailingSlash,
+  addTrailingSlash,
+  removeTrailingSlash,
+} from '@docusaurus/utils-common';
 import {
   createFromExtensionsRedirects,
   createToExtensionsRedirects,

packages/docusaurus-plugin-client-redirects/src/extensionRedirects.ts

@@ -9,7 +9,7 @@ import {
   addTrailingSlash,
   removeSuffix,
   removeTrailingSlash,
-} from '@docusaurus/utils';
+} from '@docusaurus/utils-common';
 import type {RedirectItem} from './types';
 
 const ExtensionAdditionalMessage =

packages/docusaurus-plugin-client-redirects/src/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
+import {addLeadingSlash, removePrefix} from '@docusaurus/utils-common';
 import collectRedirects from './collectRedirects';
 import writeRedirectFiles, {
   toRedirectFiles,

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

@@ -1,12 +1,24 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./src/*": "./src/*",
+    "./client": {
+      "type": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    ".": {
+      "types": "./src/plugin-content-blog.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
   "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
+    "build": "tsc --build",
+    "watch": "tsc --build --watch",
     "test:generate-build-snap": "yarn docusaurus build src/__tests__/__fixtures__/website --out-dir build-snap && yarn rimraf src/__tests__/__fixtures__/website/.docusaurus && yarn rimraf src/__tests__/__fixtures__/website/build-snap/assets && git add src/__tests__/__fixtures__/website/build-snap"
   },
   "repository": {
@@ -19,13 +31,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.0.0",
-    "@docusaurus/logger": "3.0.0",
-    "@docusaurus/mdx-loader": "3.0.0",
-    "@docusaurus/types": "3.0.0",
-    "@docusaurus/utils": "3.0.0",
-    "@docusaurus/utils-common": "3.0.0",
-    "@docusaurus/utils-validation": "3.0.0",
+    "@docusaurus/core": "3.2.0",
+    "@docusaurus/logger": "3.2.0",
+    "@docusaurus/mdx-loader": "3.2.0",
+    "@docusaurus/types": "3.2.0",
+    "@docusaurus/utils": "3.2.0",
+    "@docusaurus/utils-common": "3.2.0",
+    "@docusaurus/utils-validation": "3.2.0",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
@@ -43,5 +55,8 @@
   },
   "engines": {
     "node": ">=18.0"
+  },
+  "devDependencies": {
+    "@total-typescript/shoehorn": "^0.1.2"
   }
 }

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website-blog-with-last-update/blog/author.md

@@ -0,0 +1,9 @@
+---
+title: Author
+slug: author
+author: ozaki
+last_update:
+  author: seb
+---
+
+author

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website-blog-with-last-update/blog/both.md

@@ -0,0 +1,11 @@
+---
+title: Both
+slug: both
+date: 2020-01-01
+last_update:
+  date: 2021-01-01
+  author: seb
+author: ozaki
+---
+
+last update date

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website-blog-with-last-update/blog/lastUpdateDate.md

@@ -0,0 +1,9 @@
+---
+title: Last update date
+slug: lastUpdateDate
+date: 2020-01-01
+last_update: 
+  date: 2021-01-01
+---
+
+last update date

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website-blog-with-last-update/blog/nothing.md

@@ -0,0 +1,6 @@
+---
+title: Nothing
+slug: nothing
+---
+
+nothing

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

@@ -23,7 +23,32 @@ title: This post links to another one!
 [Linked post](/blog/2018/12/14/Happy-First-Birthday-Slash)"
 `;
 
-exports[`paginateBlogPosts generates right pages 1`] = `
+exports[`paginateBlogPosts generates a single page 1`] = `
+[
+  {
+    "items": [
+      "post1",
+      "post2",
+      "post3",
+      "post4",
+      "post5",
+    ],
+    "metadata": {
+      "blogDescription": "Blog Description",
+      "blogTitle": "Blog Title",
+      "nextPage": undefined,
+      "page": 1,
+      "permalink": "/",
+      "postsPerPage": 10,
+      "previousPage": undefined,
+      "totalCount": 5,
+      "totalPages": 1,
+    },
+  },
+]
+`;
+
+exports[`paginateBlogPosts generates pages 1`] = `
 [
   {
     "items": [
@@ -78,7 +103,7 @@ exports[`paginateBlogPosts generates right pages 1`] = `
 ]
 `;
 
-exports[`paginateBlogPosts generates right pages 2`] = `
+exports[`paginateBlogPosts generates pages at blog root 1`] = `
 [
   {
     "items": [
@@ -133,26 +158,56 @@ exports[`paginateBlogPosts generates right pages 2`] = `
 ]
 `;
 
-exports[`paginateBlogPosts generates right pages 3`] = `
+exports[`paginateBlogPosts generates pages with custom pageBasePath 1`] = `
 [
   {
     "items": [
       "post1",
       "post2",
+    ],
+    "metadata": {
+      "blogDescription": "Blog Description",
+      "blogTitle": "Blog Title",
+      "nextPage": "/blog/customPageBasePath/2",
+      "page": 1,
+      "permalink": "/blog",
+      "postsPerPage": 2,
+      "previousPage": undefined,
+      "totalCount": 5,
+      "totalPages": 3,
+    },
+  },
+  {
+    "items": [
       "post3",
       "post4",
+    ],
+    "metadata": {
+      "blogDescription": "Blog Description",
+      "blogTitle": "Blog Title",
+      "nextPage": "/blog/customPageBasePath/3",
+      "page": 2,
+      "permalink": "/blog/customPageBasePath/2",
+      "postsPerPage": 2,
+      "previousPage": "/blog",
+      "totalCount": 5,
+      "totalPages": 3,
+    },
+  },
+  {
+    "items": [
       "post5",
     ],
     "metadata": {
       "blogDescription": "Blog Description",
       "blogTitle": "Blog Title",
       "nextPage": undefined,
-      "page": 1,
-      "permalink": "/",
-      "postsPerPage": 10,
-      "previousPage": undefined,
+      "page": 3,
+      "permalink": "/blog/customPageBasePath/3",
+      "postsPerPage": 2,
+      "previousPage": "/blog/customPageBasePath/2",
       "totalCount": 5,
-      "totalPages": 1,
+      "totalPages": 3,
     },
   },
 ]

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

@@ -220,6 +220,134 @@ exports[`atom has feed item for each post 1`] = `
 ]
 `;
 
+exports[`atom has feed item for each post - with trailing slash 1`] = `
+[
+  "<?xml version="1.0" encoding="utf-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+    <id>https://docusaurus.io/myBaseUrl/blog/</id>
+    <title>Hello Blog</title>
+    <updated>2023-07-23T00:00:00.000Z</updated>
+    <generator>https://github.com/jpmonette/feed</generator>
+    <link rel="alternate" href="https://docusaurus.io/myBaseUrl/blog/"/>
+    <subtitle>Hello Blog</subtitle>
+    <icon>https://docusaurus.io/myBaseUrl/image/favicon.ico</icon>
+    <rights>Copyright</rights>
+    <entry>
+        <title type="html"><![CDATA[test links]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/blog-with-links/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/blog-with-links/"/>
+        <updated>2023-07-23T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[absolute full url]]></summary>
+        <content type="html"><![CDATA[<p><a href="https://github.com/facebook/docusaurus" target="_blank" rel="noopener noreferrer">absolute full url</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">absolute pathname</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">relative pathname</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">md link</a></p>
+<p><a href="https://docusaurus.io/myBaseUrl/blog/blog-with-links/#title">anchor</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title#title">relative pathname + anchor</a></p>
+<p><img loading="lazy" src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png" width="760" height="160" class="img_yGFe"></p>
+<p><img loading="lazy" src="https://docusaurus.io/assets/images/slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg" alt="" class="img_yGFe"></p>
+<img srcset="https://docusaurus.io/img/test-image.png 300w, https://docusaurus.io/img/docusaurus-social-card.png 500w">
+<img src="https://docusaurus.io/img/test-image.png">]]></content>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[MDX Blog Sample with require calls]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/"/>
+        <updated>2021-03-06T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[Test MDX with require calls]]></summary>
+        <content type="html"><![CDATA[<p>Test MDX with require calls</p>
+<!-- -->
+<!-- -->
+<img src="https://docusaurus.io/img/test-image.png">
+<img src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png">
+<img src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png">]]></content>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[Full Blog Sample]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/"/>
+        <updated>2021-03-05T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[HTML Heading 1]]></summary>
+        <content type="html"><![CDATA[<h1>HTML Heading 1</h1>
+<h2>HTML Heading 2</h2>
+<p>HTML Paragraph</p>
+<!-- -->
+<!-- -->
+<p>Import DOM</p>
+<h1>Heading 1</h1>
+<h2 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-2">Heading 2<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-2" class="hash-link" aria-label="Direct link to Heading 2" title="Direct link to Heading 2">​</a></h2>
+<h3 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-3">Heading 3<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-3" class="hash-link" aria-label="Direct link to Heading 3" title="Direct link to Heading 3">​</a></h3>
+<h4 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-4">Heading 4<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-4" class="hash-link" aria-label="Direct link to Heading 4" title="Direct link to Heading 4">​</a></h4>
+<h5 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-5">Heading 5<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-5" class="hash-link" aria-label="Direct link to Heading 5" title="Direct link to Heading 5">​</a></h5>
+<ul>
+<li>list1</li>
+<li>list2</li>
+<li>list3</li>
+</ul>
+<ul>
+<li>list1</li>
+<li>list2</li>
+<li>list3</li>
+</ul>
+<p>Normal Text <em>Italics Text</em> <strong>Bold Text</strong></p>
+<p><a href="https://v2.docusaurus.io/" target="_blank" rel="noopener noreferrer">link</a> <img loading="lazy" src="https://v2.docusaurus.io/" alt="image" class="img_yGFe"></p>]]></content>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[Complex Slug]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/"/>
+        <updated>2020-08-16T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[complex url slug]]></summary>
+        <content type="html"><![CDATA[<p>complex url slug</p>]]></content>
+        <category label="date" term="date"/>
+        <category label="complex" term="complex"/>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[Simple Slug]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/simple/slug/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/simple/slug/"/>
+        <updated>2020-08-15T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[simple url slug]]></summary>
+        <content type="html"><![CDATA[<p>simple url slug</p>]]></content>
+        <author>
+            <name>Sébastien Lorber</name>
+            <uri>https://sebastienlorber.com</uri>
+        </author>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[some heading]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/heading-as-title/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/heading-as-title/"/>
+        <updated>2019-01-02T00:00:00.000Z</updated>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[date-matter]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/date-matter/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/date-matter/"/>
+        <updated>2019-01-01T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[date inside front matter]]></summary>
+        <content type="html"><![CDATA[<p>date inside front matter</p>]]></content>
+        <category label="date" term="date"/>
+    </entry>
+    <entry>
+        <title type="html"><![CDATA[Happy 1st Birthday Slash! (translated)]]></title>
+        <id>https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/</id>
+        <link href="https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/"/>
+        <updated>2018-12-14T00:00:00.000Z</updated>
+        <summary type="html"><![CDATA[Happy birthday! (translated)]]></summary>
+        <content type="html"><![CDATA[<p>Happy birthday! (translated)</p>]]></content>
+        <author>
+            <name>Yangshun Tay (translated)</name>
+        </author>
+        <author>
+            <name>Sébastien Lorber (translated)</name>
+            <email>lorber.sebastien@gmail.com</email>
+        </author>
+    </entry>
+</feed>",
+]
+`;
+
 exports[`json filters to the first two entries 1`] = `
 [
   "{
@@ -378,6 +506,102 @@ exports[`json has feed item for each post 1`] = `
 ]
 `;
 
+exports[`json has feed item for each post - with trailing slash 1`] = `
+[
+  "{
+    "version": "https://jsonfeed.org/version/1",
+    "title": "Hello Blog",
+    "home_page_url": "https://docusaurus.io/myBaseUrl/blog/",
+    "description": "Hello Blog",
+    "items": [
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/blog-with-links/",
+            "content_html": "<p><a href=\\"https://github.com/facebook/docusaurus\\" target=\\"_blank\\" rel=\\"noopener noreferrer\\">absolute full url</a></p>/n<p><a href=\\"https://docusaurus.io/blog/heading-as-title\\">absolute pathname</a></p>/n<p><a href=\\"https://docusaurus.io/blog/heading-as-title\\">relative pathname</a></p>/n<p><a href=\\"https://docusaurus.io/blog/heading-as-title\\">md link</a></p>/n<p><a href=\\"https://docusaurus.io/myBaseUrl/blog/blog-with-links/#title\\">anchor</a></p>/n<p><a href=\\"https://docusaurus.io/blog/heading-as-title#title\\">relative pathname + anchor</a></p>/n<p><img loading=\\"lazy\\" src=\\"https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png\\" width=\\"760\\" height=\\"160\\" class=\\"img_yGFe\\"></p>/n<p><img loading=\\"lazy\\" src=\\"https://docusaurus.io/assets/images/slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg\\" alt=\\"\\" class=\\"img_yGFe\\"></p>/n<img srcset=\\"https://docusaurus.io/img/test-image.png 300w, https://docusaurus.io/img/docusaurus-social-card.png 500w\\">/n<img src=\\"https://docusaurus.io/img/test-image.png\\">",
+            "url": "https://docusaurus.io/myBaseUrl/blog/blog-with-links/",
+            "title": "test links",
+            "summary": "absolute full url",
+            "date_modified": "2023-07-23T00:00:00.000Z",
+            "tags": []
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/",
+            "content_html": "<p>Test MDX with require calls</p>/n<!-- -->/n<!-- -->/n<img src=\\"https://docusaurus.io/img/test-image.png\\">/n<img src=\\"https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png\\">/n<img src=\\"https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png\\">",
+            "url": "https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/",
+            "title": "MDX Blog Sample with require calls",
+            "summary": "Test MDX with require calls",
+            "date_modified": "2021-03-06T00:00:00.000Z",
+            "tags": []
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/",
+            "content_html": "<h1>HTML Heading 1</h1>/n<h2>HTML Heading 2</h2>/n<p>HTML Paragraph</p>/n<!-- -->/n<!-- -->/n<p>Import DOM</p>/n<h1>Heading 1</h1>/n<h2 class=\\"anchor anchorWithHideOnScrollNavbar_G5V2\\" id=\\"heading-2\\">Heading 2<a href=\\"https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-2\\" class=\\"hash-link\\" aria-label=\\"Direct link to Heading 2\\" title=\\"Direct link to Heading 2\\">​</a></h2>/n<h3 class=\\"anchor anchorWithHideOnScrollNavbar_G5V2\\" id=\\"heading-3\\">Heading 3<a href=\\"https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-3\\" class=\\"hash-link\\" aria-label=\\"Direct link to Heading 3\\" title=\\"Direct link to Heading 3\\">​</a></h3>/n<h4 class=\\"anchor anchorWithHideOnScrollNavbar_G5V2\\" id=\\"heading-4\\">Heading 4<a href=\\"https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-4\\" class=\\"hash-link\\" aria-label=\\"Direct link to Heading 4\\" title=\\"Direct link to Heading 4\\">​</a></h4>/n<h5 class=\\"anchor anchorWithHideOnScrollNavbar_G5V2\\" id=\\"heading-5\\">Heading 5<a href=\\"https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-5\\" class=\\"hash-link\\" aria-label=\\"Direct link to Heading 5\\" title=\\"Direct link to Heading 5\\">​</a></h5>/n<ul>/n<li>list1</li>/n<li>list2</li>/n<li>list3</li>/n</ul>/n<ul>/n<li>list1</li>/n<li>list2</li>/n<li>list3</li>/n</ul>/n<p>Normal Text <em>Italics Text</em> <strong>Bold Text</strong></p>/n<p><a href=\\"https://v2.docusaurus.io/\\" target=\\"_blank\\" rel=\\"noopener noreferrer\\">link</a> <img loading=\\"lazy\\" src=\\"https://v2.docusaurus.io/\\" alt=\\"image\\" class=\\"img_yGFe\\"></p>",
+            "url": "https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/",
+            "title": "Full Blog Sample",
+            "summary": "HTML Heading 1",
+            "date_modified": "2021-03-05T00:00:00.000Z",
+            "tags": []
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/",
+            "content_html": "<p>complex url slug</p>",
+            "url": "https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/",
+            "title": "Complex Slug",
+            "summary": "complex url slug",
+            "date_modified": "2020-08-16T00:00:00.000Z",
+            "tags": [
+                "date",
+                "complex"
+            ]
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/simple/slug/",
+            "content_html": "<p>simple url slug</p>",
+            "url": "https://docusaurus.io/myBaseUrl/blog/simple/slug/",
+            "title": "Simple Slug",
+            "summary": "simple url slug",
+            "date_modified": "2020-08-15T00:00:00.000Z",
+            "author": {
+                "name": "Sébastien Lorber",
+                "url": "https://sebastienlorber.com"
+            },
+            "tags": []
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/heading-as-title/",
+            "content_html": "",
+            "url": "https://docusaurus.io/myBaseUrl/blog/heading-as-title/",
+            "title": "some heading",
+            "date_modified": "2019-01-02T00:00:00.000Z",
+            "tags": []
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/date-matter/",
+            "content_html": "<p>date inside front matter</p>",
+            "url": "https://docusaurus.io/myBaseUrl/blog/date-matter/",
+            "title": "date-matter",
+            "summary": "date inside front matter",
+            "date_modified": "2019-01-01T00:00:00.000Z",
+            "tags": [
+                "date"
+            ]
+        },
+        {
+            "id": "https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/",
+            "content_html": "<p>Happy birthday! (translated)</p>",
+            "url": "https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/",
+            "title": "Happy 1st Birthday Slash! (translated)",
+            "summary": "Happy birthday! (translated)",
+            "date_modified": "2018-12-14T00:00:00.000Z",
+            "author": {
+                "name": "Yangshun Tay (translated)"
+            },
+            "tags": []
+        }
+    ]
+}",
+]
+`;
+
 exports[`rss filters to the first two entries 1`] = `
 [
   "<?xml version="1.0" encoding="utf-8"?>
@@ -593,3 +817,123 @@ exports[`rss has feed item for each post 1`] = `
 </rss>",
 ]
 `;
+
+exports[`rss has feed item for each post - with trailing slash 1`] = `
+[
+  "<?xml version="1.0" encoding="utf-8"?>
+<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
+    <channel>
+        <title>Hello Blog</title>
+        <link>https://docusaurus.io/myBaseUrl/blog/</link>
+        <description>Hello Blog</description>
+        <lastBuildDate>Sun, 23 Jul 2023 00:00:00 GMT</lastBuildDate>
+        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
+        <generator>https://github.com/jpmonette/feed</generator>
+        <language>en</language>
+        <copyright>Copyright</copyright>
+        <item>
+            <title><![CDATA[test links]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/blog-with-links/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/blog-with-links/</guid>
+            <pubDate>Sun, 23 Jul 2023 00:00:00 GMT</pubDate>
+            <description><![CDATA[absolute full url]]></description>
+            <content:encoded><![CDATA[<p><a href="https://github.com/facebook/docusaurus" target="_blank" rel="noopener noreferrer">absolute full url</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">absolute pathname</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">relative pathname</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title">md link</a></p>
+<p><a href="https://docusaurus.io/myBaseUrl/blog/blog-with-links/#title">anchor</a></p>
+<p><a href="https://docusaurus.io/blog/heading-as-title#title">relative pathname + anchor</a></p>
+<p><img loading="lazy" src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png" width="760" height="160" class="img_yGFe"></p>
+<p><img loading="lazy" src="https://docusaurus.io/assets/images/slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg" alt="" class="img_yGFe"></p>
+<img srcset="https://docusaurus.io/img/test-image.png 300w, https://docusaurus.io/img/docusaurus-social-card.png 500w">
+<img src="https://docusaurus.io/img/test-image.png">]]></content:encoded>
+        </item>
+        <item>
+            <title><![CDATA[MDX Blog Sample with require calls]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post/</guid>
+            <pubDate>Sat, 06 Mar 2021 00:00:00 GMT</pubDate>
+            <description><![CDATA[Test MDX with require calls]]></description>
+            <content:encoded><![CDATA[<p>Test MDX with require calls</p>
+<!-- -->
+<!-- -->
+<img src="https://docusaurus.io/img/test-image.png">
+<img src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png">
+<img src="https://docusaurus.io/assets/images/test-image-742d39e51f41482e8132e79c09ad4eea.png">]]></content:encoded>
+        </item>
+        <item>
+            <title><![CDATA[Full Blog Sample]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/</guid>
+            <pubDate>Fri, 05 Mar 2021 00:00:00 GMT</pubDate>
+            <description><![CDATA[HTML Heading 1]]></description>
+            <content:encoded><![CDATA[<h1>HTML Heading 1</h1>
+<h2>HTML Heading 2</h2>
+<p>HTML Paragraph</p>
+<!-- -->
+<!-- -->
+<p>Import DOM</p>
+<h1>Heading 1</h1>
+<h2 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-2">Heading 2<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-2" class="hash-link" aria-label="Direct link to Heading 2" title="Direct link to Heading 2">​</a></h2>
+<h3 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-3">Heading 3<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-3" class="hash-link" aria-label="Direct link to Heading 3" title="Direct link to Heading 3">​</a></h3>
+<h4 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-4">Heading 4<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-4" class="hash-link" aria-label="Direct link to Heading 4" title="Direct link to Heading 4">​</a></h4>
+<h5 class="anchor anchorWithHideOnScrollNavbar_G5V2" id="heading-5">Heading 5<a href="https://docusaurus.io/myBaseUrl/blog/mdx-blog-post/#heading-5" class="hash-link" aria-label="Direct link to Heading 5" title="Direct link to Heading 5">​</a></h5>
+<ul>
+<li>list1</li>
+<li>list2</li>
+<li>list3</li>
+</ul>
+<ul>
+<li>list1</li>
+<li>list2</li>
+<li>list3</li>
+</ul>
+<p>Normal Text <em>Italics Text</em> <strong>Bold Text</strong></p>
+<p><a href="https://v2.docusaurus.io/" target="_blank" rel="noopener noreferrer">link</a> <img loading="lazy" src="https://v2.docusaurus.io/" alt="image" class="img_yGFe"></p>]]></content:encoded>
+        </item>
+        <item>
+            <title><![CDATA[Complex Slug]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/hey/my super path/héllô/</guid>
+            <pubDate>Sun, 16 Aug 2020 00:00:00 GMT</pubDate>
+            <description><![CDATA[complex url slug]]></description>
+            <content:encoded><![CDATA[<p>complex url slug</p>]]></content:encoded>
+            <category>date</category>
+            <category>complex</category>
+        </item>
+        <item>
+            <title><![CDATA[Simple Slug]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/simple/slug/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/simple/slug/</guid>
+            <pubDate>Sat, 15 Aug 2020 00:00:00 GMT</pubDate>
+            <description><![CDATA[simple url slug]]></description>
+            <content:encoded><![CDATA[<p>simple url slug</p>]]></content:encoded>
+        </item>
+        <item>
+            <title><![CDATA[some heading]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/heading-as-title/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/heading-as-title/</guid>
+            <pubDate>Wed, 02 Jan 2019 00:00:00 GMT</pubDate>
+        </item>
+        <item>
+            <title><![CDATA[date-matter]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/date-matter/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/date-matter/</guid>
+            <pubDate>Tue, 01 Jan 2019 00:00:00 GMT</pubDate>
+            <description><![CDATA[date inside front matter]]></description>
+            <content:encoded><![CDATA[<p>date inside front matter</p>]]></content:encoded>
+            <category>date</category>
+        </item>
+        <item>
+            <title><![CDATA[Happy 1st Birthday Slash! (translated)]]></title>
+            <link>https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/</link>
+            <guid>https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash/</guid>
+            <pubDate>Fri, 14 Dec 2018 00:00:00 GMT</pubDate>
+            <description><![CDATA[Happy birthday! (translated)]]></description>
+            <content:encoded><![CDATA[<p>Happy birthday! (translated)</p>]]></content:encoded>
+            <author>lorber.sebastien@gmail.com (Sébastien Lorber (translated))</author>
+        </item>
+    </channel>
+</rss>",
+]
+`;

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

@@ -1,5 +1,250 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`blog plugin process blog posts load content 1`] = `
+{
+  "/blog/tags/tag-1": {
+    "items": [
+      "/simple/slug/another",
+      "/another/tags",
+      "/another/tags2",
+    ],
+    "label": "tag1",
+    "pages": [
+      {
+        "items": [
+          "/simple/slug/another",
+        ],
+        "metadata": {
+          "blogDescription": "Blog",
+          "blogTitle": "Blog",
+          "nextPage": "/blog/tags/tag-1/page/2",
+          "page": 1,
+          "permalink": "/blog/tags/tag-1",
+          "postsPerPage": 1,
+          "previousPage": undefined,
+          "totalCount": 3,
+          "totalPages": 3,
+        },
+      },
+      {
+        "items": [
+          "/another/tags",
+        ],
+        "metadata": {
+          "blogDescription": "Blog",
+          "blogTitle": "Blog",
+          "nextPage": "/blog/tags/tag-1/page/3",
+          "page": 2,
+          "permalink": "/blog/tags/tag-1/page/2",
+          "postsPerPage": 1,
+          "previousPage": "/blog/tags/tag-1",
+          "totalCount": 3,
+          "totalPages": 3,
+        },
+      },
+      {
+        "items": [
+          "/another/tags2",
+        ],
+        "metadata": {
+          "blogDescription": "Blog",
+          "blogTitle": "Blog",
+          "nextPage": undefined,
+          "page": 3,
+          "permalink": "/blog/tags/tag-1/page/3",
+          "postsPerPage": 1,
+          "previousPage": "/blog/tags/tag-1/page/2",
+          "totalCount": 3,
+          "totalPages": 3,
+        },
+      },
+    ],
+    "permalink": "/blog/tags/tag-1",
+    "unlisted": false,
+  },
+  "/blog/tags/tag-2": {
+    "items": [
+      "/another/tags",
+      "/another/tags2",
+    ],
+    "label": "tag2",
+    "pages": [
+      {
+        "items": [
+          "/another/tags",
+        ],
+        "metadata": {
+          "blogDescription": "Blog",
+          "blogTitle": "Blog",
+          "nextPage": "/blog/tags/tag-2/page/2",
+          "page": 1,
+          "permalink": "/blog/tags/tag-2",
+          "postsPerPage": 1,
+          "previousPage": undefined,
+          "totalCount": 2,
+          "totalPages": 2,
+        },
+      },
+      {
+        "items": [
+          "/another/tags2",
+        ],
+        "metadata": {
+          "blogDescription": "Blog",
+          "blogTitle": "Blog",
+          "nextPage": undefined,
+          "page": 2,
+          "permalink": "/blog/tags/tag-2/page/2",
+          "postsPerPage": 1,
+          "previousPage": "/blog/tags/tag-2",
+          "totalCount": 2,
+          "totalPages": 2,
+        },
+      },
+    ],
+    "permalink": "/blog/tags/tag-2",
+    "unlisted": false,
+  },
+}
+`;
+
+exports[`blog plugin process blog posts load content 2`] = `
+[
+  {
+    "content": "simple url slug",
+    "id": "/simple/slug/another",
+    "metadata": {
+      "authors": [
+        {
+          "imageURL": undefined,
+          "name": "Sébastien Lorber",
+          "title": "Docusaurus maintainer",
+          "url": "https://sebastienlorber.com",
+        },
+      ],
+      "date": 2020-08-15T00:00:00.000Z,
+      "description": "simple url slug",
+      "editUrl": "https://baseEditUrl.com/edit/blog/another-simple-slug-with-tags.md",
+      "frontMatter": {
+        "author": "Sébastien Lorber",
+        "author_title": "Docusaurus maintainer",
+        "author_url": "https://sebastienlorber.com",
+        "date": 2020-08-15T00:00:00.000Z,
+        "slug": "/simple/slug/another",
+        "tags": [
+          "tag1",
+        ],
+        "title": "Another Simple Slug",
+      },
+      "hasTruncateMarker": false,
+      "lastUpdatedAt": undefined,
+      "lastUpdatedBy": undefined,
+      "nextItem": {
+        "permalink": "/blog/another/tags",
+        "title": "Another With Tag",
+      },
+      "permalink": "/blog/simple/slug/another",
+      "readingTime": 0.015,
+      "source": "@site/blog/another-simple-slug-with-tags.md",
+      "tags": [
+        {
+          "label": "tag1",
+          "permalink": "/blog/tags/tag-1",
+        },
+      ],
+      "title": "Another Simple Slug",
+      "unlisted": false,
+    },
+  },
+  {
+    "content": "with tag",
+    "id": "/another/tags",
+    "metadata": {
+      "authors": [],
+      "date": 2020-08-15T00:00:00.000Z,
+      "description": "with tag",
+      "editUrl": "https://baseEditUrl.com/edit/blog/another-with-tags.md",
+      "frontMatter": {
+        "date": 2020-08-15T00:00:00.000Z,
+        "slug": "/another/tags",
+        "tags": [
+          "tag1",
+          "tag2",
+        ],
+        "title": "Another With Tag",
+      },
+      "hasTruncateMarker": false,
+      "lastUpdatedAt": undefined,
+      "lastUpdatedBy": undefined,
+      "nextItem": {
+        "permalink": "/blog/another/tags2",
+        "title": "Another With Tag",
+      },
+      "permalink": "/blog/another/tags",
+      "prevItem": {
+        "permalink": "/blog/simple/slug/another",
+        "title": "Another Simple Slug",
+      },
+      "readingTime": 0.01,
+      "source": "@site/blog/another-with-tags.md",
+      "tags": [
+        {
+          "label": "tag1",
+          "permalink": "/blog/tags/tag-1",
+        },
+        {
+          "label": "tag2",
+          "permalink": "/blog/tags/tag-2",
+        },
+      ],
+      "title": "Another With Tag",
+      "unlisted": false,
+    },
+  },
+  {
+    "content": "with tag",
+    "id": "/another/tags2",
+    "metadata": {
+      "authors": [],
+      "date": 2020-08-15T00:00:00.000Z,
+      "description": "with tag",
+      "editUrl": "https://baseEditUrl.com/edit/blog/another-with-tags2.md",
+      "frontMatter": {
+        "date": 2020-08-15T00:00:00.000Z,
+        "slug": "/another/tags2",
+        "tags": [
+          "tag1",
+          "tag2",
+        ],
+        "title": "Another With Tag",
+      },
+      "hasTruncateMarker": false,
+      "lastUpdatedAt": undefined,
+      "lastUpdatedBy": undefined,
+      "permalink": "/blog/another/tags2",
+      "prevItem": {
+        "permalink": "/blog/another/tags",
+        "title": "Another With Tag",
+      },
+      "readingTime": 0.01,
+      "source": "@site/blog/another-with-tags2.md",
+      "tags": [
+        {
+          "label": "tag1",
+          "permalink": "/blog/tags/tag-1",
+        },
+        {
+          "label": "tag2",
+          "permalink": "/blog/tags/tag-2",
+        },
+      ],
+      "title": "Another With Tag",
+      "unlisted": false,
+    },
+  },
+]
+`;
+
 exports[`blog plugin works on blog tags without pagination 1`] = `
 {
   "/blog/tags/tag-1": {

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

@@ -50,7 +50,6 @@ exports[`translateContent falls back when translation is incomplete 1`] = `
         "authors": [],
         "date": 2021-07-19T00:00:00.000Z,
         "description": "/blog/2021/06/19/hello",
-        "formattedDate": "June 19, 2021",
         "frontMatter": {},
         "hasTruncateMarker": true,
         "permalink": "/blog/2021/06/19/hello",
@@ -94,7 +93,6 @@ exports[`translateContent returns translated loaded 1`] = `
         "authors": [],
         "date": 2021-07-19T00:00:00.000Z,
         "description": "/blog/2021/06/19/hello",
-        "formattedDate": "June 19, 2021",
         "frontMatter": {},
         "hasTruncateMarker": true,
         "permalink": "/blog/2021/06/19/hello",

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

@@ -19,6 +19,7 @@ describe('getBlogPostAuthors', () => {
       getBlogPostAuthors({
         frontMatter: {},
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([]);
     expect(
@@ -27,6 +28,7 @@ describe('getBlogPostAuthors', () => {
           authors: [],
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([]);
   });
@@ -38,6 +40,7 @@ describe('getBlogPostAuthors', () => {
           author: 'Sébastien Lorber',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([{name: 'Sébastien Lorber'}]);
     expect(
@@ -46,6 +49,7 @@ describe('getBlogPostAuthors', () => {
           authorTitle: 'maintainer',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([{title: 'maintainer'}]);
     expect(
@@ -54,11 +58,30 @@ describe('getBlogPostAuthors', () => {
           authorImageURL: 'https://github.com/slorber.png',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([{imageURL: 'https://github.com/slorber.png'}]);
     expect(
       getBlogPostAuthors({
         frontMatter: {
+          authorImageURL: '/img/slorber.png',
+        },
+        authorsMap: undefined,
+        baseUrl: '/',
+      }),
+    ).toEqual([{imageURL: '/img/slorber.png'}]);
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
+          authorImageURL: '/img/slorber.png',
+        },
+        authorsMap: undefined,
+        baseUrl: '/baseURL',
+      }),
+    ).toEqual([{imageURL: '/baseURL/img/slorber.png'}]);
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
           author: 'Sébastien Lorber',
           author_title: 'maintainer1',
           authorTitle: 'maintainer2',
@@ -68,6 +91,7 @@ describe('getBlogPostAuthors', () => {
           authorURL: 'https://github.com/slorber2',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([
       {
@@ -86,8 +110,69 @@ describe('getBlogPostAuthors', () => {
           authors: 'slorber',
         },
         authorsMap: {slorber: {name: 'Sébastien Lorber'}},
+        baseUrl: '/',
       }),
     ).toEqual([{key: 'slorber', name: 'Sébastien Lorber'}]);
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
+          authors: 'slorber',
+        },
+        authorsMap: {
+          slorber: {
+            name: 'Sébastien Lorber',
+            imageURL: 'https://github.com/slorber.png',
+          },
+        },
+        baseUrl: '/',
+      }),
+    ).toEqual([
+      {
+        key: 'slorber',
+        name: 'Sébastien Lorber',
+        imageURL: 'https://github.com/slorber.png',
+      },
+    ]);
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
+          authors: 'slorber',
+        },
+        authorsMap: {
+          slorber: {
+            name: 'Sébastien Lorber',
+            imageURL: '/img/slorber.png',
+          },
+        },
+        baseUrl: '/',
+      }),
+    ).toEqual([
+      {
+        key: 'slorber',
+        name: 'Sébastien Lorber',
+        imageURL: '/img/slorber.png',
+      },
+    ]);
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
+          authors: 'slorber',
+        },
+        authorsMap: {
+          slorber: {
+            name: 'Sébastien Lorber',
+            imageURL: '/img/slorber.png',
+          },
+        },
+        baseUrl: '/baseUrl',
+      }),
+    ).toEqual([
+      {
+        key: 'slorber',
+        name: 'Sébastien Lorber',
+        imageURL: '/baseUrl/img/slorber.png',
+      },
+    ]);
   });
 
   it('can read authors string[]', () => {
@@ -100,6 +185,7 @@ describe('getBlogPostAuthors', () => {
           slorber: {name: 'Sébastien Lorber', title: 'maintainer'},
           yangshun: {name: 'Yangshun Tay'},
         },
+        baseUrl: '/',
       }),
     ).toEqual([
       {key: 'slorber', name: 'Sébastien Lorber', title: 'maintainer'},
@@ -114,6 +200,7 @@ describe('getBlogPostAuthors', () => {
           authors: {name: 'Sébastien Lorber', title: 'maintainer'},
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([{name: 'Sébastien Lorber', title: 'maintainer'}]);
   });
@@ -128,6 +215,7 @@ describe('getBlogPostAuthors', () => {
           ],
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toEqual([
       {name: 'Sébastien Lorber', title: 'maintainer'},
@@ -153,6 +241,7 @@ describe('getBlogPostAuthors', () => {
           slorber: {name: 'Sébastien Lorber', title: 'maintainer'},
           yangshun: {name: 'Yangshun Tay', title: 'Yangshun title original'},
         },
+        baseUrl: '/',
       }),
     ).toEqual([
       {key: 'slorber', name: 'Sébastien Lorber', title: 'maintainer'},
@@ -173,6 +262,7 @@ describe('getBlogPostAuthors', () => {
           authors: 'slorber',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "Can't reference blog post authors by a key (such as 'slorber') because no authors map file could be loaded.
@@ -187,6 +277,7 @@ describe('getBlogPostAuthors', () => {
           authors: 'slorber',
         },
         authorsMap: {},
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "Can't reference blog post authors by a key (such as 'slorber') because no authors map file could be loaded.
@@ -205,6 +296,7 @@ describe('getBlogPostAuthors', () => {
           yangshun: {name: 'Yangshun Tay'},
           jmarcey: {name: 'Joel Marcey'},
         },
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "Blog author with key "slorber" not found in the authors map file.
@@ -225,6 +317,7 @@ describe('getBlogPostAuthors', () => {
           yangshun: {name: 'Yangshun Tay'},
           jmarcey: {name: 'Joel Marcey'},
         },
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "Blog author with key "slorber" not found in the authors map file.
@@ -245,6 +338,7 @@ describe('getBlogPostAuthors', () => {
           yangshun: {name: 'Yangshun Tay'},
           jmarcey: {name: 'Joel Marcey'},
         },
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "Blog author with key "slorber" not found in the authors map file.
@@ -262,6 +356,7 @@ describe('getBlogPostAuthors', () => {
           author: 'Yangshun Tay',
         },
         authorsMap: undefined,
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "To declare blog post authors, use the 'authors' front matter in priority.
@@ -275,6 +370,7 @@ describe('getBlogPostAuthors', () => {
           author_title: 'legacy title',
         },
         authorsMap: {slorber: {name: 'Sébastien Lorber'}},
+        baseUrl: '/',
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
       "To declare blog post authors, use the 'authors' front matter in priority.

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

@@ -8,12 +8,14 @@
 import {jest} from '@jest/globals';
 import fs from 'fs-extra';
 import path from 'path';
+import {fromPartial} from '@total-typescript/shoehorn';
 import {
   truncate,
   parseBlogFileName,
   linkify,
   getSourceToPermalink,
   paginateBlogPosts,
+  applyProcessBlogPosts,
   type LinkifyParams,
 } from '../blogUtils';
 import type {BlogBrokenMarkdownLink, BlogContentPaths} from '../types';
@@ -38,14 +40,15 @@ describe('truncate', () => {
 });
 
 describe('paginateBlogPosts', () => {
-  it('generates right pages', () => {
-    const blogPosts = [
-      {id: 'post1', metadata: {}, content: 'Foo 1'},
-      {id: 'post2', metadata: {}, content: 'Foo 2'},
-      {id: 'post3', metadata: {}, content: 'Foo 3'},
-      {id: 'post4', metadata: {}, content: 'Foo 4'},
-      {id: 'post5', metadata: {}, content: 'Foo 5'},
-    ] as BlogPost[];
+  const blogPosts = [
+    {id: 'post1', metadata: {}, content: 'Foo 1'},
+    {id: 'post2', metadata: {}, content: 'Foo 2'},
+    {id: 'post3', metadata: {}, content: 'Foo 3'},
+    {id: 'post4', metadata: {}, content: 'Foo 4'},
+    {id: 'post5', metadata: {}, content: 'Foo 5'},
+  ] as BlogPost[];
+
+  it('generates pages', () => {
     expect(
       paginateBlogPosts({
         blogPosts,
@@ -53,8 +56,12 @@ describe('paginateBlogPosts', () => {
         blogTitle: 'Blog Title',
         blogDescription: 'Blog Description',
         postsPerPageOption: 2,
+        pageBasePath: 'page',
       }),
     ).toMatchSnapshot();
+  });
+
+  it('generates pages at blog root', () => {
     expect(
       paginateBlogPosts({
         blogPosts,
@@ -62,8 +69,12 @@ describe('paginateBlogPosts', () => {
         blogTitle: 'Blog Title',
         blogDescription: 'Blog Description',
         postsPerPageOption: 2,
+        pageBasePath: 'page',
       }),
     ).toMatchSnapshot();
+  });
+
+  it('generates a single page', () => {
     expect(
       paginateBlogPosts({
         blogPosts,
@@ -71,6 +82,20 @@ describe('paginateBlogPosts', () => {
         blogTitle: 'Blog Title',
         blogDescription: 'Blog Description',
         postsPerPageOption: 10,
+        pageBasePath: 'page',
+      }),
+    ).toMatchSnapshot();
+  });
+
+  it('generates pages with custom pageBasePath', () => {
+    expect(
+      paginateBlogPosts({
+        blogPosts,
+        basePageUrl: '/blog',
+        blogTitle: 'Blog Title',
+        blogDescription: 'Blog Description',
+        postsPerPageOption: 2,
+        pageBasePath: 'customPageBasePath',
       }),
     ).toMatchSnapshot();
   });
@@ -213,7 +238,7 @@ describe('linkify', () => {
         hasTruncateMarker: false,
         frontMatter: {},
         authors: [],
-        formattedDate: '',
+        unlisted: false,
       },
       content: '',
     },
@@ -272,3 +297,81 @@ describe('linkify', () => {
     } as BlogBrokenMarkdownLink);
   });
 });
+
+describe('processBlogPosts', () => {
+  const blogPost2022: BlogPost = fromPartial({
+    metadata: {date: new Date('2022-01-01')},
+  });
+  const blogPost2023: BlogPost = fromPartial({
+    metadata: {date: new Date('2023-01-01')},
+  });
+  const blogPost2024: BlogPost = fromPartial({
+    metadata: {date: new Date('2024-01-01')},
+  });
+
+  it('filter blogs only from 2024', async () => {
+    const processedBlogPosts = await applyProcessBlogPosts({
+      blogPosts: [blogPost2022, blogPost2023, blogPost2024],
+      processBlogPosts: async ({blogPosts}: {blogPosts: BlogPost[]}) =>
+        blogPosts.filter(
+          (blogPost) => blogPost.metadata.date.getFullYear() === 2024,
+        ),
+    });
+
+    expect(processedBlogPosts).toEqual([blogPost2024]);
+  });
+
+  it('sort blogs by date in ascending order', async () => {
+    const processedBlogPosts = await applyProcessBlogPosts({
+      blogPosts: [blogPost2023, blogPost2022, blogPost2024],
+      processBlogPosts: async ({blogPosts}: {blogPosts: BlogPost[]}) =>
+        blogPosts.sort(
+          (a, b) => a.metadata.date.getTime() - b.metadata.date.getTime(),
+        ),
+    });
+
+    expect(processedBlogPosts).toEqual([
+      blogPost2022,
+      blogPost2023,
+      blogPost2024,
+    ]);
+  });
+
+  it('sort blogs by date in descending order', async () => {
+    const processedBlogPosts = await applyProcessBlogPosts({
+      blogPosts: [blogPost2023, blogPost2022, blogPost2024],
+      processBlogPosts: async ({blogPosts}: {blogPosts: BlogPost[]}) =>
+        blogPosts.sort(
+          (a, b) => b.metadata.date.getTime() - a.metadata.date.getTime(),
+        ),
+    });
+
+    expect(processedBlogPosts).toEqual([
+      blogPost2024,
+      blogPost2023,
+      blogPost2022,
+    ]);
+  });
+
+  it('processBlogPosts return 2022 only', async () => {
+    const processedBlogPosts = await applyProcessBlogPosts({
+      blogPosts: [blogPost2023, blogPost2022, blogPost2024],
+      processBlogPosts: async () => [blogPost2022],
+    });
+
+    expect(processedBlogPosts).toEqual([blogPost2022]);
+  });
+
+  it('processBlogPosts return undefined', async () => {
+    const processedBlogPosts = await applyProcessBlogPosts({
+      blogPosts: [blogPost2023, blogPost2022, blogPost2024],
+      processBlogPosts: async () => {},
+    });
+
+    expect(processedBlogPosts).toEqual([
+      blogPost2023,
+      blogPost2022,
+      blogPost2024,
+    ]);
+  });
+});

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

@@ -8,6 +8,8 @@
 import {jest} from '@jest/globals';
 import path from 'path';
 import fs from 'fs-extra';
+import {DEFAULT_PARSE_FRONT_MATTER} from '@docusaurus/utils';
+import {fromPartial} from '@total-typescript/shoehorn';
 import {DEFAULT_OPTIONS} from '../options';
 import {generateBlogPosts} from '../blogUtils';
 import {createBlogFeedFiles} from '../feed';
@@ -31,6 +33,8 @@ const DefaultI18N: I18n = {
   },
 };
 
+const markdown = {parseFrontMatter: DEFAULT_PARSE_FRONT_MATTER};
+
 function getBlogContentPaths(siteDir: string): BlogContentPaths {
   return {
     contentPath: path.resolve(siteDir, 'blog'),
@@ -72,16 +76,17 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
       baseUrl: '/',
       url: 'https://docusaurus.io',
       favicon: 'image/favicon.ico',
+      markdown,
     };
     const outDir = path.join(siteDir, 'build-snap');
 
     await testGenerateFeeds(
-      {
+      fromPartial({
         siteDir,
         siteConfig,
         i18n: DefaultI18N,
         outDir,
-      } as LoadContext,
+      }),
       {
         path: 'invalid-blog-path',
         routeBasePath: 'blog',
@@ -110,17 +115,18 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
       baseUrl: '/myBaseUrl/',
       url: 'https://docusaurus.io',
       favicon: 'image/favicon.ico',
+      markdown,
     };
 
     // Build is quite difficult to mock, so we built the blog beforehand and
     // copied the output to the fixture...
     await testGenerateFeeds(
-      {
+      fromPartial({
         siteDir,
         siteConfig,
         i18n: DefaultI18N,
         outDir,
-      } as LoadContext,
+      }),
       {
         path: 'blog',
         routeBasePath: 'blog',
@@ -152,17 +158,18 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
       baseUrl: '/myBaseUrl/',
       url: 'https://docusaurus.io',
       favicon: 'image/favicon.ico',
+      markdown,
     };
 
     // Build is quite difficult to mock, so we built the blog beforehand and
     // copied the output to the fixture...
     await testGenerateFeeds(
-      {
+      fromPartial({
         siteDir,
         siteConfig,
         i18n: DefaultI18N,
         outDir,
-      } as LoadContext,
+      }),
       {
         path: 'blog',
         routeBasePath: 'blog',
@@ -204,17 +211,18 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
       baseUrl: '/myBaseUrl/',
       url: 'https://docusaurus.io',
       favicon: 'image/favicon.ico',
+      markdown,
     };
 
     // Build is quite difficult to mock, so we built the blog beforehand and
     // copied the output to the fixture...
     await testGenerateFeeds(
-      {
+      fromPartial({
         siteDir,
         siteConfig,
         i18n: DefaultI18N,
         outDir,
-      } as LoadContext,
+      }),
       {
         path: 'blog',
         routeBasePath: 'blog',
@@ -238,4 +246,48 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
     ).toMatchSnapshot();
     fsMock.mockClear();
   });
+
+  it('has feed item for each post - with trailing slash', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'website');
+    const outDir = path.join(siteDir, 'build-snap');
+    const siteConfig = {
+      title: 'Hello',
+      baseUrl: '/myBaseUrl/',
+      url: 'https://docusaurus.io',
+      favicon: 'image/favicon.ico',
+      trailingSlash: true,
+      markdown,
+    };
+
+    // Build is quite difficult to mock, so we built the blog beforehand and
+    // copied the output to the fixture...
+    await testGenerateFeeds(
+      fromPartial({
+        siteDir,
+        siteConfig,
+        i18n: DefaultI18N,
+        outDir,
+      }),
+      {
+        path: 'blog',
+        routeBasePath: 'blog',
+        tagsBasePath: 'tags',
+        authorsMapPath: 'authors.yml',
+        include: DEFAULT_OPTIONS.include,
+        exclude: DEFAULT_OPTIONS.exclude,
+        feedOptions: {
+          type: [feedType],
+          copyright: 'Copyright',
+        },
+        readingTime: ({content, defaultReadingTime}) =>
+          defaultReadingTime({content}),
+        truncateMarker: /<!--\s*truncate\s*-->/,
+      } as PluginOptions,
+    );
+
+    expect(
+      fsMock.mock.calls.map((call) => call[1] as string),
+    ).toMatchSnapshot();
+    fsMock.mockClear();
+  });
 });

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

@@ -8,7 +8,11 @@
 import {jest} from '@jest/globals';
 import path from 'path';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
-import {posixPath, getFileCommitDate} from '@docusaurus/utils';
+import {
+  posixPath,
+  getFileCommitDate,
+  LAST_UPDATE_FALLBACK,
+} from '@docusaurus/utils';
 import pluginContentBlog from '../index';
 import {validateOptions} from '../options';
 import type {
@@ -16,6 +20,7 @@ import type {
   LoadContext,
   I18n,
   Validate,
+  MarkdownConfig,
 } from '@docusaurus/types';
 import type {
   BlogPost,
@@ -24,6 +29,25 @@ import type {
   EditUrlFunction,
 } from '@docusaurus/plugin-content-blog';
 
+const markdown: MarkdownConfig = {
+  format: 'mdx',
+  mermaid: true,
+  mdx1Compat: {
+    comments: true,
+    headingIds: true,
+    admonitions: true,
+  },
+  parseFrontMatter: async (params) => {
+    // Reuse the default parser
+    const result = await params.defaultParseFrontMatter(params);
+    if (result.frontMatter.title === 'Complex Slug') {
+      result.frontMatter.custom_frontMatter = 'added by parseFrontMatter';
+    }
+    return result;
+  },
+  remarkRehypeOptions: undefined,
+};
+
 function findByTitle(
   blogPosts: BlogPost[],
   title: string,
@@ -81,6 +105,7 @@ const getPlugin = async (
     title: 'Hello',
     baseUrl: '/',
     url: 'https://docusaurus.io',
+    markdown,
   } as DocusaurusConfig;
   return pluginContentBlog(
     {
@@ -155,7 +180,6 @@ describe('blog plugin', () => {
       description: `date inside front matter`,
       authors: [],
       date: new Date('2019-01-01'),
-      formattedDate: 'January 1, 2019',
       frontMatter: {
         date: new Date('2019-01-01'),
         tags: ['date'],
@@ -200,7 +224,6 @@ describe('blog plugin', () => {
         },
       ],
       date: new Date('2018-12-14'),
-      formattedDate: 'December 14, 2018',
       frontMatter: {
         authors: [
           {
@@ -236,12 +259,12 @@ describe('blog plugin', () => {
         title: 'Simple Slug',
       },
       date: new Date('2020-08-16'),
-      formattedDate: 'August 16, 2020',
       frontMatter: {
         date: '2020/08/16',
         slug: '/hey/my super path/héllô',
         title: 'Complex Slug',
         tags: ['date', 'complex'],
+        custom_frontMatter: 'added by parseFrontMatter',
       },
       tags: [
         {
@@ -281,7 +304,6 @@ describe('blog plugin', () => {
         title: 'draft',
       },
       date: new Date('2020-08-15'),
-      formattedDate: 'August 15, 2020',
       frontMatter: {
         author: 'Sébastien Lorber',
         author_title: 'Docusaurus maintainer',
@@ -307,7 +329,6 @@ describe('blog plugin', () => {
       description: '',
       authors: [],
       date: new Date('2019-01-02'),
-      formattedDate: 'January 2, 2019',
       frontMatter: {
         date: new Date('2019-01-02'),
       },
@@ -322,39 +343,6 @@ describe('blog plugin', () => {
     });
   });
 
-  it('builds simple website blog with localized dates', async () => {
-    const siteDir = path.join(__dirname, '__fixtures__', 'website');
-    const blogPostsFrench = await getBlogPosts(siteDir, {}, getI18n('fr'));
-    expect(blogPostsFrench).toHaveLength(10);
-    expect(blogPostsFrench[0]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"23 juillet 2023"`,
-    );
-    expect(blogPostsFrench[1]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"6 mars 2021"`,
-    );
-    expect(blogPostsFrench[2]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"5 mars 2021"`,
-    );
-    expect(blogPostsFrench[3]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"16 août 2020"`,
-    );
-    expect(blogPostsFrench[4]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"15 août 2020"`,
-    );
-    expect(blogPostsFrench[5]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"27 février 2020"`,
-    );
-    expect(blogPostsFrench[6]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"27 février 2020"`,
-    );
-    expect(blogPostsFrench[7]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"2 janvier 2019"`,
-    );
-    expect(blogPostsFrench[8]!.metadata.formattedDate).toMatchInlineSnapshot(
-      `"1 janvier 2019"`,
-    );
-  });
-
   it('handles edit URL with editLocalizedBlogs: true', async () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
     const blogPosts = await getBlogPosts(siteDir, {editLocalizedFiles: true});
@@ -453,13 +441,8 @@ describe('blog plugin', () => {
     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 = getFileCommitDate(noDateSourceFile, {age: 'oldest'});
+    const result = await getFileCommitDate(noDateSourceFile, {age: 'oldest'});
     const noDateSourceTime = result.date;
-    const formattedDate = Intl.DateTimeFormat('en', {
-      day: 'numeric',
-      month: 'long',
-      year: 'numeric',
-    }).format(noDateSourceTime);
 
     expect({
       ...getByTitle(blogPosts, 'no date').metadata,
@@ -473,7 +456,6 @@ describe('blog plugin', () => {
       description: `no date`,
       authors: [],
       date: noDateSourceTime,
-      formattedDate,
       frontMatter: {},
       tags: [],
       prevItem: undefined,
@@ -520,4 +502,165 @@ describe('blog plugin', () => {
 
     expect(blogTags).toMatchSnapshot();
   });
+
+  it('process blog posts load content', async () => {
+    const siteDir = path.join(
+      __dirname,
+      '__fixtures__',
+      'website-blog-with-tags',
+    );
+    const plugin = await getPlugin(
+      siteDir,
+      {
+        postsPerPage: 1,
+        processBlogPosts: async ({blogPosts}) =>
+          blogPosts.filter((blog) => blog.metadata.tags[0]?.label === 'tag1'),
+      },
+      DefaultI18N,
+    );
+    const {blogPosts, blogTags, blogListPaginated} =
+      (await plugin.loadContent!())!;
+
+    expect(blogListPaginated).toHaveLength(3);
+
+    expect(Object.keys(blogTags)).toHaveLength(2);
+    expect(blogTags).toMatchSnapshot();
+
+    expect(blogPosts).toHaveLength(3);
+    expect(blogPosts).toMatchSnapshot();
+  });
+});
+
+describe('last update', () => {
+  const siteDir = path.join(
+    __dirname,
+    '__fixtures__',
+    'website-blog-with-last-update',
+  );
+
+  const lastUpdateFor = (date: string) => new Date(date).getTime();
+
+  it('author and time', async () => {
+    const plugin = await getPlugin(
+      siteDir,
+      {
+        showLastUpdateAuthor: true,
+        showLastUpdateTime: true,
+      },
+      DefaultI18N,
+    );
+    const {blogPosts} = (await plugin.loadContent!())!;
+
+    expect(blogPosts[0]?.metadata.lastUpdatedBy).toBe('seb');
+    expect(blogPosts[0]?.metadata.lastUpdatedAt).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+    );
+
+    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedBy,
+    );
+    expect(blogPosts[1]?.metadata.lastUpdatedAt).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+    );
+
+    expect(blogPosts[2]?.metadata.lastUpdatedBy).toBe('seb');
+    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(
+      lastUpdateFor('2021-01-01'),
+    );
+
+    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedBy,
+    );
+    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(
+      lastUpdateFor('2021-01-01'),
+    );
+  });
+
+  it('time only', async () => {
+    const plugin = await getPlugin(
+      siteDir,
+      {
+        showLastUpdateAuthor: false,
+        showLastUpdateTime: true,
+      },
+      DefaultI18N,
+    );
+    const {blogPosts} = (await plugin.loadContent!())!;
+
+    expect(blogPosts[0]?.metadata.title).toBe('Author');
+    expect(blogPosts[0]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[0]?.metadata.lastUpdatedAt).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+    );
+
+    expect(blogPosts[1]?.metadata.title).toBe('Nothing');
+    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[1]?.metadata.lastUpdatedAt).toBe(
+      LAST_UPDATE_FALLBACK.lastUpdatedAt,
+    );
+
+    expect(blogPosts[2]?.metadata.title).toBe('Both');
+    expect(blogPosts[2]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBe(
+      lastUpdateFor('2021-01-01'),
+    );
+
+    expect(blogPosts[3]?.metadata.title).toBe('Last update date');
+    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBe(
+      lastUpdateFor('2021-01-01'),
+    );
+  });
+
+  it('author only', async () => {
+    const plugin = await getPlugin(
+      siteDir,
+      {
+        showLastUpdateAuthor: true,
+        showLastUpdateTime: false,
+      },
+      DefaultI18N,
+    );
+    const {blogPosts} = (await plugin.loadContent!())!;
+
+    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.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.lastUpdatedAt).toBeUndefined();
+  });
+
+  it('none', async () => {
+    const plugin = await getPlugin(
+      siteDir,
+      {
+        showLastUpdateAuthor: false,
+        showLastUpdateTime: false,
+      },
+      DefaultI18N,
+    );
+    const {blogPosts} = (await plugin.loadContent!())!;
+
+    expect(blogPosts[0]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[0]?.metadata.lastUpdatedAt).toBeUndefined();
+
+    expect(blogPosts[1]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[1]?.metadata.lastUpdatedAt).toBeUndefined();
+
+    expect(blogPosts[2]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[2]?.metadata.lastUpdatedAt).toBeUndefined();
+
+    expect(blogPosts[3]?.metadata.lastUpdatedBy).toBeUndefined();
+    expect(blogPosts[3]?.metadata.lastUpdatedAt).toBeUndefined();
+  });
 });

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

@@ -29,7 +29,6 @@ const sampleBlogPosts: BlogPost[] = [
       source: '/blog/2021/06/19/hello',
       description: '/blog/2021/06/19/hello',
       date: new Date(2021, 6, 19),
-      formattedDate: 'June 19, 2021',
       tags: [],
       title: 'Hello',
       hasTruncateMarker: true,

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {getDataFileData} from '@docusaurus/utils';
+import {getDataFileData, normalizeUrl} from '@docusaurus/utils';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
 import type {BlogContentPaths} from './types';
 import type {
@@ -68,17 +68,37 @@ export async function getAuthorsMap(params: {
 type AuthorsParam = {
   frontMatter: BlogPostFrontMatter;
   authorsMap: AuthorsMap | undefined;
+  baseUrl: string;
 };
 
+function normalizeImageUrl({
+  imageURL,
+  baseUrl,
+}: {
+  imageURL: string | undefined;
+  baseUrl: string;
+}) {
+  return imageURL?.startsWith('/')
+    ? normalizeUrl([baseUrl, imageURL])
+    : imageURL;
+}
+
 // Legacy v1/early-v2 front matter fields
 // We may want to deprecate those in favor of using only frontMatter.authors
-function getFrontMatterAuthorLegacy(
-  frontMatter: BlogPostFrontMatter,
-): Author | undefined {
+function getFrontMatterAuthorLegacy({
+  baseUrl,
+  frontMatter,
+}: {
+  baseUrl: string;
+  frontMatter: BlogPostFrontMatter;
+}): Author | undefined {
   const name = frontMatter.author;
   const title = frontMatter.author_title ?? frontMatter.authorTitle;
   const url = frontMatter.author_url ?? frontMatter.authorURL;
-  const imageURL = frontMatter.author_image_url ?? frontMatter.authorImageURL;
+  const imageURL = normalizeImageUrl({
+    imageURL: frontMatter.author_image_url ?? frontMatter.authorImageURL,
+    baseUrl,
+  });
 
   if (name || title || url || imageURL) {
     return {
@@ -148,14 +168,26 @@ ${Object.keys(authorsMap)
   return frontMatterAuthors.map(toAuthor);
 }
 
+function fixAuthorImageBaseURL(
+  authors: Author[],
+  {baseUrl}: {baseUrl: string},
+) {
+  return authors.map((author) => ({
+    ...author,
+    imageURL: normalizeImageUrl({imageURL: author.imageURL, baseUrl}),
+  }));
+}
+
 export function getBlogPostAuthors(params: AuthorsParam): Author[] {
-  const authorLegacy = getFrontMatterAuthorLegacy(params.frontMatter);
+  const authorLegacy = getFrontMatterAuthorLegacy(params);
   const authors = getFrontMatterAuthors(params);
 
+  const updatedAuthors = fixAuthorImageBaseURL(authors, params);
+
   if (authorLegacy) {
     // Technically, we could allow mixing legacy/authors front matter, but do we
     // really want to?
-    if (authors.length > 0) {
+    if (updatedAuthors.length > 0) {
       throw new Error(
         `To declare blog post authors, use the 'authors' front matter in priority.
 Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.`,
@@ -164,5 +196,5 @@ Don't mix 'authors' with other existing 'author_*' front matter. Choose one or t
     return [authorLegacy];
   }
 
-  return authors;
+  return updatedAuthors;
 }

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

@@ -11,7 +11,7 @@ import _ from 'lodash';
 import logger from '@docusaurus/logger';
 import readingTime from 'reading-time';
 import {
-  parseMarkdownString,
+  parseMarkdownFile,
   normalizeUrl,
   aliasedSitePath,
   getEditUrl,
@@ -26,10 +26,11 @@ import {
   getContentPathList,
   isUnlisted,
   isDraft,
+  readLastUpdateData,
 } from '@docusaurus/utils';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
-import type {LoadContext} from '@docusaurus/types';
+import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
   PluginOptions,
   ReadingTimeFunction,
@@ -57,12 +58,14 @@ export function paginateBlogPosts({
   blogTitle,
   blogDescription,
   postsPerPageOption,
+  pageBasePath,
 }: {
   blogPosts: BlogPost[];
   basePageUrl: string;
   blogTitle: string;
   blogDescription: string;
   postsPerPageOption: number | 'ALL';
+  pageBasePath: string;
 }): BlogPaginated[] {
   const totalCount = blogPosts.length;
   const postsPerPage =
@@ -73,7 +76,7 @@ export function paginateBlogPosts({
 
   function permalink(page: number) {
     return page > 0
-      ? normalizeUrl([basePageUrl, `page/${page + 1}`])
+      ? normalizeUrl([basePageUrl, pageBasePath, `${page + 1}`])
       : basePageUrl;
   }
 
@@ -111,6 +114,7 @@ export function getBlogTags({
   blogTitle: string;
   blogDescription: string;
   postsPerPageOption: number | 'ALL';
+  pageBasePath: string;
 }): BlogTags {
   const groups = groupTaggedItems(
     blogPosts,
@@ -161,29 +165,19 @@ export function parseBlogFileName(
   return {date: undefined, text, slug};
 }
 
-function formatBlogPostDate(
-  locale: string,
-  date: Date,
-  calendar: string,
-): string {
+async function parseBlogPostMarkdownFile({
+  filePath,
+  parseFrontMatter,
+}: {
+  filePath: string;
+  parseFrontMatter: ParseFrontMatter;
+}) {
+  const fileContent = await fs.readFile(filePath, 'utf-8');
   try {
-    return new Intl.DateTimeFormat(locale, {
-      day: 'numeric',
-      month: 'long',
-      year: 'numeric',
-      timeZone: 'UTC',
-      calendar,
-    }).format(date);
-  } catch (err) {
-    logger.error`Can't format blog post date "${String(date)}"`;
-    throw err;
-  }
-}
-
-async function parseBlogPostMarkdownFile(blogSourceAbsolute: string) {
-  const markdownString = await fs.readFile(blogSourceAbsolute, 'utf-8');
-  try {
-    const result = parseMarkdownString(markdownString, {
+    const result = await parseMarkdownFile({
+      filePath,
+      fileContent,
+      parseFrontMatter,
       removeContentTitle: true,
     });
     return {
@@ -191,7 +185,7 @@ async function parseBlogPostMarkdownFile(blogSourceAbsolute: string) {
       frontMatter: validateBlogPostFrontMatter(result.frontMatter),
     };
   } catch (err) {
-    logger.error`Error while parsing blog post file path=${blogSourceAbsolute}.`;
+    logger.error`Error while parsing blog post file path=${filePath}.`;
     throw err;
   }
 }
@@ -207,7 +201,10 @@ async function processBlogSourceFile(
   authorsMap?: AuthorsMap,
 ): Promise<BlogPost | undefined> {
   const {
-    siteConfig: {baseUrl},
+    siteConfig: {
+      baseUrl,
+      markdown: {parseFrontMatter},
+    },
     siteDir,
     i18n,
   } = context;
@@ -228,10 +225,19 @@ async function processBlogSourceFile(
   const blogSourceAbsolute = path.join(blogDirPath, blogSourceRelative);
 
   const {frontMatter, content, contentTitle, excerpt} =
-    await parseBlogPostMarkdownFile(blogSourceAbsolute);
+    await parseBlogPostMarkdownFile({
+      filePath: blogSourceAbsolute,
+      parseFrontMatter,
+    });
 
   const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir);
 
+  const lastUpdate = await readLastUpdateData(
+    blogSourceAbsolute,
+    options,
+    frontMatter.last_update,
+  );
+
   const draft = isDraft({frontMatter});
   const unlisted = isUnlisted({frontMatter});
 
@@ -259,10 +265,11 @@ async function processBlogSourceFile(
     }
 
     try {
-      const result = getFileCommitDate(blogSourceAbsolute, {
+      const result = await getFileCommitDate(blogSourceAbsolute, {
         age: 'oldest',
         includeAuthor: false,
       });
+
       return result.date;
     } catch (err) {
       logger.warn(err);
@@ -271,11 +278,6 @@ async function processBlogSourceFile(
   }
 
   const date = await getDate();
-  const formattedDate = formatBlogPostDate(
-    i18n.currentLocale,
-    date,
-    i18n.localeConfigs[i18n.currentLocale]!.calendar,
-  );
 
   const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
   const description = frontMatter.description ?? excerpt ?? '';
@@ -319,7 +321,7 @@ async function processBlogSourceFile(
     routeBasePath,
     tagsRouteBasePath,
   ]);
-  const authors = getBlogPostAuthors({authorsMap, frontMatter});
+  const authors = getBlogPostAuthors({authorsMap, frontMatter, baseUrl});
 
   return {
     id: slug,
@@ -330,7 +332,6 @@ async function processBlogSourceFile(
       title,
       description,
       date,
-      formattedDate,
       tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
       readingTime: showReadingTime
         ? options.readingTime({
@@ -343,6 +344,8 @@ async function processBlogSourceFile(
       authors,
       frontMatter,
       unlisted,
+      lastUpdatedAt: lastUpdate.lastUpdatedAt,
+      lastUpdatedBy: lastUpdate.lastUpdatedBy,
     },
     content,
   };
@@ -428,3 +431,19 @@ export function linkify({
 
   return newContent;
 }
+
+export async function applyProcessBlogPosts({
+  blogPosts,
+  processBlogPosts,
+}: {
+  blogPosts: BlogPost[];
+  processBlogPosts: PluginOptions['processBlogPosts'];
+}): Promise<BlogPost[]> {
+  const processedBlogPosts = await processBlogPosts({blogPosts});
+
+  if (Array.isArray(processedBlogPosts)) {
+    return processedBlogPosts;
+  }
+
+  return blogPosts;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 useRouteContext from '@docusaurus/useRouteContext';
+import type {BlogMetadata} from '@docusaurus/plugin-content-blog';
+
+export function useBlogMetadata(): BlogMetadata {
+  const routeContext = useRouteContext();
+  const blogMetadata = routeContext?.data?.blogMetadata;
+  if (!blogMetadata) {
+    throw new Error(
+      "useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context",
+    );
+  }
+  return blogMetadata as BlogMetadata;
+}

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

@@ -11,7 +11,10 @@ import logger from '@docusaurus/logger';
 import {Feed, type Author as FeedAuthor} from 'feed';
 import * as srcset from 'srcset';
 import {normalizeUrl, readOutputHTMLFile} from '@docusaurus/utils';
-import {blogPostContainerID} from '@docusaurus/utils-common';
+import {
+  blogPostContainerID,
+  applyTrailingSlash,
+} from '@docusaurus/utils-common';
 import {load as cheerioLoad} from 'cheerio';
 import type {DocusaurusConfig} from '@docusaurus/types';
 import type {
@@ -40,8 +43,14 @@ async function generateBlogFeed({
   }
 
   const {feedOptions, routeBasePath} = options;
-  const {url: siteUrl, baseUrl, title, favicon} = siteConfig;
-  const blogBaseUrl = normalizeUrl([siteUrl, baseUrl, routeBasePath]);
+  const {url: siteUrl, baseUrl, title, favicon, trailingSlash} = siteConfig;
+  const blogBaseUrl = applyTrailingSlash(
+    normalizeUrl([siteUrl, baseUrl, routeBasePath]),
+    {
+      trailingSlash,
+      baseUrl,
+    },
+  );
 
   const blogPostsForFeed =
     feedOptions.limit === false || feedOptions.limit === null
@@ -85,7 +94,7 @@ async function defaultCreateFeedItems({
   siteConfig: DocusaurusConfig;
   outDir: string;
 }): Promise<BlogFeedItem[]> {
-  const {url: siteUrl} = siteConfig;
+  const {url: siteUrl, baseUrl, trailingSlash} = siteConfig;
 
   function toFeedAuthor(author: Author): FeedAuthor {
     return {name: author.name, link: author.url, email: author.email};
@@ -105,13 +114,19 @@ async function defaultCreateFeedItems({
       } = post;
 
       const content = await readOutputHTMLFile(
-        permalink.replace(siteConfig.baseUrl, ''),
+        permalink.replace(baseUrl, ''),
         outDir,
-        siteConfig.trailingSlash,
+        trailingSlash,
       );
       const $ = cheerioLoad(content);
 
-      const blogPostAbsoluteUrl = normalizeUrl([siteUrl, permalink]);
+      const blogPostAbsoluteUrl = applyTrailingSlash(
+        normalizeUrl([siteUrl, permalink]),
+        {
+          trailingSlash,
+          baseUrl,
+        },
+      );
 
       const toAbsoluteUrl = (src: string) =>
         String(new URL(src, blogPostAbsoluteUrl));

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

@@ -4,14 +4,14 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 import {
+  ContentVisibilitySchema,
+  FrontMatterLastUpdateSchema,
+  FrontMatterTOCHeadingLevels,
+  FrontMatterTagsSchema,
   JoiFrontMatter as Joi, // Custom instance for front matter
   URISchema,
   validateFrontMatter,
-  FrontMatterTagsSchema,
-  FrontMatterTOCHeadingLevels,
-  ContentVisibilitySchema,
 } from '@docusaurus/utils-validation';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
@@ -69,6 +69,7 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   hide_table_of_contents: Joi.boolean(),
 
   ...FrontMatterTOCHeadingLevels,
+  last_update: FrontMatterLastUpdateSchema,
 })
   .messages({
     'deprecate.error':

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

@@ -11,6 +11,7 @@ import {
   normalizeUrl,
   docuHash,
   aliasedSitePath,
+  aliasedSitePathToRelativePath,
   getPluginI18nPath,
   posixPath,
   addTrailingPathSeparator,
@@ -20,11 +21,12 @@ import {
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import {
-  generateBlogPosts,
   getSourceToPermalink,
   getBlogTags,
   paginateBlogPosts,
   shouldBeListed,
+  applyProcessBlogPosts,
+  generateBlogPosts,
 } from './blogUtils';
 import footnoteIDFixer from './remark/footnoteIDFixer';
 import {translateContent, getTranslationFiles} from './translations';
@@ -32,7 +34,12 @@ import {createBlogFeedFiles} from './feed';
 
 import {toTagProp, toTagsProp} from './props';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
-import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
+import type {
+  LoadContext,
+  Plugin,
+  HtmlTags,
+  RouteMetadata,
+} from '@docusaurus/types';
 import type {
   PluginOptions,
   BlogPostFrontMatter,
@@ -42,6 +49,7 @@ import type {
   BlogTags,
   BlogContent,
   BlogPaginated,
+  BlogMetadata,
 } from '@docusaurus/plugin-content-blog';
 
 export default async function pluginContentBlog(
@@ -107,11 +115,16 @@ export default async function pluginContentBlog(
         blogDescription,
         blogTitle,
         blogSidebarTitle,
+        pageBasePath,
       } = options;
 
       const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
       const blogTagsListPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
-      const blogPosts = await generateBlogPosts(contentPaths, context, options);
+      let blogPosts = await generateBlogPosts(contentPaths, context, options);
+      blogPosts = await applyProcessBlogPosts({
+        blogPosts,
+        processBlogPosts: options.processBlogPosts,
+      });
       const listedBlogPosts = blogPosts.filter(shouldBeListed);
 
       if (!blogPosts.length) {
@@ -121,11 +134,10 @@ export default async function pluginContentBlog(
           blogListPaginated: [],
           blogTags: {},
           blogTagsListPath,
-          blogTagsPaginated: [],
         };
       }
 
-      // Colocate next and prev metadata.
+      // Collocate next and prev metadata.
       listedBlogPosts.forEach((blogPost, index) => {
         const prevItem = index > 0 ? listedBlogPosts[index - 1] : null;
         if (prevItem) {
@@ -153,6 +165,7 @@ export default async function pluginContentBlog(
         blogDescription,
         postsPerPageOption,
         basePageUrl: baseBlogUrl,
+        pageBasePath,
       });
 
       const blogTags: BlogTags = getBlogTags({
@@ -160,6 +173,7 @@ export default async function pluginContentBlog(
         postsPerPageOption,
         blogDescription,
         blogTitle,
+        pageBasePath,
       });
 
       return {
@@ -180,6 +194,7 @@ export default async function pluginContentBlog(
         blogArchiveComponent,
         routeBasePath,
         archiveBasePath,
+        blogTitle,
       } = options;
 
       const {addRoute, createData} = actions;
@@ -255,6 +270,24 @@ export default async function pluginContentBlog(
         ),
       );
 
+      const blogMetadata: BlogMetadata = {
+        blogBasePath: normalizeUrl([baseUrl, routeBasePath]),
+        blogTitle,
+      };
+      const blogMetadataPath = await createData(
+        `blogMetadata-${pluginId}.json`,
+        JSON.stringify(blogMetadata, null, 2),
+      );
+
+      function createBlogPostRouteMetadata(
+        blogPostMeta: BlogPostMetadata,
+      ): RouteMetadata {
+        return {
+          sourceFilePath: aliasedSitePathToRelativePath(blogPostMeta.source),
+          lastUpdatedAt: blogPostMeta.lastUpdatedAt,
+        };
+      }
+
       // Create routes for blog entries.
       await Promise.all(
         blogPosts.map(async (blogPost) => {
@@ -274,6 +307,10 @@ export default async function pluginContentBlog(
               sidebar: aliasedSource(sidebarProp),
               content: metadata.source,
             },
+            metadata: createBlogPostRouteMetadata(metadata),
+            context: {
+              blogMetadata: aliasedSource(blogMetadataPath),
+            },
           });
 
           blogItemsToMetadata[id] = metadata;

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

@@ -45,11 +45,15 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   routeBasePath: 'blog',
   tagsBasePath: 'tags',
   archiveBasePath: 'archive',
+  pageBasePath: 'page',
   path: 'blog',
   editLocalizedFiles: false,
   authorsMapPath: 'authors.yml',
   readingTime: ({content, defaultReadingTime}) => defaultReadingTime({content}),
   sortPosts: 'descending',
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
+  processBlogPosts: async () => undefined,
 };
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -59,6 +63,7 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     .allow(null),
   routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
   tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
+  pageBasePath: Joi.string().default(DEFAULT_OPTIONS.pageBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   postsPerPage: Joi.alternatives()
@@ -132,6 +137,13 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   sortPosts: Joi.string()
     .valid('descending', 'ascending')
     .default(DEFAULT_OPTIONS.sortPosts),
+  showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
+  showLastUpdateAuthor: Joi.bool().default(
+    DEFAULT_OPTIONS.showLastUpdateAuthor,
+  ),
+  processBlogPosts: Joi.function()
+    .optional()
+    .default(() => DEFAULT_OPTIONS.processBlogPosts),
 }).default(DEFAULT_OPTIONS);
 
 export function validateOptions({

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

@@ -5,10 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/// <reference types="@docusaurus/module-type-aliases" />
+
 declare module '@docusaurus/plugin-content-blog' {
   import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {MDXOptions} from '@docusaurus/mdx-loader';
-  import type {FrontMatterTag, Tag} from '@docusaurus/utils';
+  import type {
+    FrontMatterTag,
+    Tag,
+    LastUpdateData,
+    FrontMatterLastUpdate,
+  } from '@docusaurus/utils';
   import type {DocusaurusConfig, Plugin, LoadContext} from '@docusaurus/types';
   import type {Item as FeedItem} from 'feed';
   import type {Overwrite} from 'utility-types';
@@ -154,6 +161,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     toc_min_heading_level?: number;
     /** Maximum TOC heading level. Must be between 2 and 6. */
     toc_max_heading_level?: number;
+    /** Allows overriding the last updated author and/or date. */
+    last_update?: FrontMatterLastUpdate;
   };
 
   export type BlogPostFrontMatterAuthor = Author & {
@@ -178,7 +187,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     | BlogPostFrontMatterAuthor
     | (string | BlogPostFrontMatterAuthor)[];
 
-  export type BlogPostMetadata = {
+  export type BlogPostMetadata = LastUpdateData & {
     /** Path to the Markdown source, with `@site` alias. */
     readonly source: string;
     /**
@@ -190,11 +199,6 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      * into a string.
      */
     readonly date: Date;
-    /**
-     * Publish date formatted according to the locale, so that the client can
-     * render the date regardless of the existence of `Intl.DateTimeFormat`.
-     */
-    readonly formattedDate: string;
     /** Full link including base URL. */
     readonly permalink: string;
     /**
@@ -333,6 +337,11 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
       defaultReadingTime: ReadingTimeFunction;
     },
   ) => number | undefined;
+
+  export type ProcessBlogPostsFn = (params: {
+    blogPosts: BlogPost[];
+  }) => Promise<void | BlogPost[]>;
+
   /**
    * Plugin options after normalization.
    */
@@ -351,10 +360,15 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     routeBasePath: string;
     /**
      * URL route for the tags section of your blog. Will be appended to
-     * `routeBasePath`. **DO NOT** include a trailing slash.
+     * `routeBasePath`.
      */
     tagsBasePath: string;
     /**
+     * URL route for the pages section of your blog. Will be appended to
+     * `routeBasePath`.
+     */
+    pageBasePath: string;
+    /**
      * URL route for the archive section of your blog. Will be appended to
      * `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to
      * disable generation of archive.
@@ -419,6 +433,14 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     readingTime: ReadingTimeFunctionOption;
     /** Governs the direction of blog post sorting. */
     sortPosts: 'ascending' | 'descending';
+    /**	Whether to display the last date the doc was updated. */
+    showLastUpdateTime: boolean;
+    /** Whether to display the author who last updated the doc. */
+    showLastUpdateAuthor: boolean;
+    /** An optional function which can be used to transform blog posts
+     *  (filter, modify, delete, etc...).
+     */
+    processBlogPosts: ProcessBlogPostsFn;
   };
 
   /**
@@ -461,6 +483,13 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     blogTagsListPath: string;
   };
 
+  export type BlogMetadata = {
+    /** the path to the base of the blog */
+    blogBasePath: string;
+    /** title of the overall blog */
+    blogTitle: string;
+  };
+
   export type BlogTags = {
     [permalink: string]: BlogTag;
   };
@@ -532,6 +561,7 @@ declare module '@theme/BlogPostPage' {
     BlogPostFrontMatter,
     BlogSidebar,
     PropBlogPostContent,
+    BlogMetadata,
   } from '@docusaurus/plugin-content-blog';
 
   export type FrontMatter = BlogPostFrontMatter;
@@ -543,6 +573,8 @@ declare module '@theme/BlogPostPage' {
     readonly sidebar: BlogSidebar;
     /** Content of this post as an MDX component, with useful metadata. */
     readonly content: Content;
+    /** Metadata about the blog. */
+    readonly blogMetadata: BlogMetadata;
   }
 
   export default function BlogPostPage(props: Props): JSX.Element;
@@ -552,6 +584,10 @@ declare module '@theme/BlogPostPage/Metadata' {
   export default function BlogPostPageMetadata(): JSX.Element;
 }
 
+declare module '@theme/BlogPostPage/StructuredData' {
+  export default function BlogPostStructuredData(): JSX.Element;
+}
+
 declare module '@theme/BlogListPage' {
   import type {Content} from '@theme/BlogPostPage';
   import type {
@@ -574,6 +610,28 @@ declare module '@theme/BlogListPage' {
   export default function BlogListPage(props: Props): JSX.Element;
 }
 
+declare module '@theme/BlogListPage/StructuredData' {
+  import type {Content} from '@theme/BlogPostPage';
+  import type {
+    BlogSidebar,
+    BlogPaginatedMetadata,
+  } from '@docusaurus/plugin-content-blog';
+
+  export interface Props {
+    /** Blog sidebar. */
+    readonly sidebar: BlogSidebar;
+    /** Metadata of the current listing page. */
+    readonly metadata: BlogPaginatedMetadata;
+    /**
+     * Array of blog posts included on this page. Every post's metadata is also
+     * available.
+     */
+    readonly items: readonly {readonly content: Content}[];
+  }
+
+  export default function BlogListPageStructuredData(props: Props): JSX.Element;
+}
+
 declare module '@theme/BlogTagsListPage' {
   import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
   import type {TagsListItem} from '@docusaurus/utils';

packages/docusaurus-plugin-content-blog/tsconfig.client.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "esnext",
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src/client", "src/*.d.ts"],
+  "exclude": ["**/__tests__/**"]
+}

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

@@ -1,5 +1,6 @@
 {
   "extends": "../../tsconfig.json",
+  "references": [{"path": "./tsconfig.client.json"}],
   "compilerOptions": {
     "noEmit": false,
     "incremental": true,
@@ -8,5 +9,5 @@
     "outDir": "lib"
   },
   "include": ["src"],
-  "exclude": ["**/__tests__/**"]
+  "exclude": ["src/client", "**/__tests__/**"]
 }

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

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

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docusaurus.config.js

@@ -11,4 +11,16 @@ module.exports = {
   url: 'https://your-docusaurus-site.example.com',
   baseUrl: '/',
   favicon: 'img/favicon.ico',
+  markdown: {
+    parseFrontMatter: async (params) => {
+      // Reuse the default parser
+      const result = await params.defaultParseFrontMatter(params);
+      if (result.frontMatter.last_update?.author) {
+        result.frontMatter.last_update.author =
+          result.frontMatter.last_update.author +
+          ' (processed by parseFrontMatter)';
+      }
+      return result;
+    },
+  },
 };