Docusaurus 3.10

我们很高兴地宣布 Docusaurus 3.10 现已发布。

这将是 v3.x 的最后一个版本，它将帮助你为 Docusaurus v4 做好准备。

Upgrading is easy. 我们遵循语义化版本，根据我们的发布流程，小版本的更新没有破坏性变更。

然而，如果你选择全局启用 future.v4: true 来迎接即将到来的 Docusaurus v4 破坏性变更，请仔细阅读下面的专属章节。

v4 Future 标志

Docusaurus v4 Future 标志允许你逐步选择启用即将到来的 Docusaurus v4 破坏性变更，并提前为 Docusaurus v4 做好准备。 您可以通过设置 future.v4: true 一次性启用它们。

This release introduces new flags and breaking changes that might break your site if you use future.v4: true and upgrade:

• future.v4.siteStorageNamespacing: In Docusaurus v4, localStorage keys will be automatically namespaced by default (theme => theme-\<hash>) to prevent key conflicts. This is likely to reset your site's visitor storage unless you migrate it to new key names. See the dedicated Site Storage section below.
• future.v4.fasterByDefault: Docusaurus Faster is now stable and will be enabled by default in Docusaurus v4. See the dedicated Docusaurus Faster section below.
• future.v4.mdx1CompatDisabledByDefault: In Docusaurus v4, MDX v1 compatibility options will be disabled by default, and you might have to adjust your docs accordingly. See the dedicated Strict MDX section below.

安全措施

npm 供应链攻击 最近激增。 正如 axios 入侵事件 所示，单个维护者或软件包被攻陷，就能波及整个生态系统，影响成千上万的下游用户。

我们已采取措施加强我们的供应链，并建议您也通过额外措施来保障自己的站点安全。

受信任的发布

我们为稳定版和预览版发布采用了 npm 可信发布。

发行版现在通过单一的 publish.yml GitHub Actions 工作流发布，并使用短期有效的 OIDC 令牌。 每个版本都有可验证的来源，透明日志显示了它的发布方式和时间。

Security Workflow

In #11874, we introduced a new security workflow that runs daily and on every pull request. It scans for suspicious dependency updates affecting our official packages and their transitive dependencies:

• Install the Docusaurus site template through the Socket Firewall to detect known malware in our dependency graph
• Check for unexpected preinstall and postinstall lifecycle scripts, using pnpm strictDepBuilds
• Check for GitHub repository and tarball URL dependencies, using pnpm blockExoticSubdeps
• Check for packages that downgrade their trust level, using pnpm trustPolicy: no-downgrade
• Run similar checks on our own monorepo, to protect Docusaurus maintainers and contributors

Security Limitations

This security workflow does not protect your site. It is designed to detect serious vulnerabilities affecting the Docusaurus ecosystem as early as possible, so we can react quickly and notify you.

With semver dependency ranges, it's impossible to guarantee a 100% secure supply chain, since any new npm release in our dependency graph can introduce a vulnerability. Ultimately, securing your site is your responsibility. At a minimum, rely on a lockfile and upgrade dependencies deliberately and cautiously.

Secure Your Site

Read the npm security best practices guide to learn how to secure your site — and npm applications in general — from compromised dependencies.

Each package manager offers different security options. In our experience, pnpm offers the best ones. We won't document all the possibilities, but here's a pnpm config example that should work well with Docusaurus:

pnpm-workspace.yaml

minimumReleaseAge: 10080

blockExoticSubdeps: true

strictDepBuilds: true
allowBuilds:
  '@swc/core': true
  core-js-pure: true
  core-js: true

trustPolicy: no-downgrade
trustPolicyExclude:
  - '[email protected]'
  - '[email protected]'

Use release cooldowns

When a popular npm package gets compromised, the community usually notices quickly and takes it down. Using a release cooldown is an effective way to reduce risk during the exposure window.

Modern package managers now offer a way to delay npm updates, giving time for security scanners to report vulnerabilities.

# npm v11.10+ - .npmrc
min-release-age=7

# pnpm v10.16+ - pnpm-workspace.yaml
minimumReleaseAge: 10080

# Yarn v4.10+ - .yarnrc.yml
npmMinimalAgeGate: "7d"

# Bun v1.3+ - bunfig.toml
[install]
minimumReleaseAge = 604800

Docusaurus Faster - Stable

Docusaurus Faster lets you opt in for our modernized build infrastructure. This includes Rspack, SWC, LightningCSS, and other optimizations.

This release improves Docusaurus Faster with a new gitEagerVcs flag and full support for Yarn PnP.

In #11802, we marked Docusaurus Faster as stable. You now need to update your config accordingly:

docusaurus.config.js

const config = {
  future: {
-   experimental_faster: true,
+   faster: true,
  },
};

Faster By Default in v4

Docusaurus Faster will be enabled by default in Docusaurus v4, and is already used for all newly initialized v3 sites. It is now part of our v4 future flags (future.v4.fasterByDefault: true) to help our community prepare for Docusaurus v4. If you haven't already, now is a good time to turn it on!

Site Storage - Stable

In #11797, we marked the config.storage API as stable. You now need to update your config accordingly:

docusaurus.config.js

 const config = {
+  storage: {
+    type: 'localStorage',
+    namespace: true,
+  },
-  future: {
-    experimental_storage: {
-      type: 'localStorage',
-      namespace: true,
-    },
-  },
 };

Automatic namespacing in v4

Docusaurus v4 will automatically namespace your storage keys to avoid localStorage key conflicts by default, and is now part of our v4 future flags (future.v4.siteStorageNamespacing: true). Instead of using a theme key, it will use theme-\<hash>.

These storage key conflicts usually happen when running multiple http://localhost:3000 apps, or when running multiple apps under the same domain (https://example.com/app and https://example.com/docs).

Strict MDX

This release introduces new MDX options to encourage stricter usage of native MDX syntax, instead of relying on proprietary Docusaurus syntax on top of MDX.

Historically, Docusaurus compiled your files with MDX v1, which was quite forgiving. Since then, the ecosystem has widely moved to MDX v3, which is stricter. Docusaurus v3.0 introduced markdown.mdx1Compat to help you upgrade incrementally.

In Docusaurus v4, we plan to turn the markdown.mdx1Compat options off by default. This upcoming change is now part of our v4 future flags (future.v4.mdx1CompatDisabledByDefault: true).

We'd like the community to adopt a stricter, native MDX syntax for a few reasons:

• This makes your docs more portable: external tools like Prettier, ESLint, TypeScript, VS Code, and GitHub can understand them.
• Docusaurus doesn't need to pre-process your documents with regular expressions before MDX compilation.
• This improves compatibility with the Unified ecosystem (Remark, MDX) and the MDX Playground.

Strict Extensions

We believe that:

• .md should be parsed as CommonMark
• .mdx should be parsed as MDX

In reality, Docusaurus has only ever supported MDX, and we should have used the .mdx extension from the start. Newly initialized sites now use .mdx by default (#11897). We encourage you to rename your existing files to .mdx as well, so that external tools can understand your content is MDX.

About CommonMark support

Although we also have experimental support for CommonMark, it still doesn't have full feature parity with MDX (issue). Once we reach full feature parity, we'll default to markdown.format: 'detect' to ensure that .md files are parsed as CommonMark instead of MDX.

Strict Admonitions

We have historically supported admonitions with titles using the :::type My Title syntax. Although convenient, this is a proprietary Docusaurus syntax.

The Markdown Directive syntax is more generic and reusable. It is not yet standardized, but widely adopted across ecosystems, including through the remark-directive package. We encourage you to migrate your admonitions to the :::type[My Title] syntax:

-:::warning Pay Attention
+:::warning[Pay Attention]

 Content

 :::

Strict Comments

MDX v3 does not support HTML comments <!-- comment -->, but supports JSX comment expressions {/* comment */}.

If you use HTML comments, we encourage you to migrate to JSX comments. For example, you can truncate blog posts with a JSX comment:

blog/my-post.mdx

 # My Blog Post

-<!-- truncate -->
+{/* truncate */}

 blog post content

Strict Heading IDs

Our historical heading IDs syntax {#my-id} is also a proprietary Docusaurus syntax, leading to ecosystem incompatibilities.

In #11755, we introduced a new heading ID syntax based on native MDX comments that we encourage you to adopt:

-## My Heading {#my-id}
+## My Heading {/* #my-id */}

In #11777, we also added an option to our write-heading-ids CLI to emit and migrate to the new syntax:

docusaurus write-heading-ids --syntax mdx-comment --migrate

VCS API - Experimental

In #11512, we added a new experimental VCS (Version Control System) API, and implemented built-in performance improvements when reading from the Git history.

Historically, Docusaurus only integrated with Git, reading the commit history to implement features such as:

• Displaying the last update date/time in the docs, blog and pages plugin when using the showLastUpdateAuthor or showLastUpdateTime options
• Displaying the blog creation date in the blog plugin
• Computing the \<lastmod> value in the sitemap plugin

This new API makes it possible to integrate Docusaurus with other VCS, such as SVN, Mercurial, a CMS or any other external system.

Here's an example implementation using hardcoded data:

docusaurus.config.ts

export default {
  future: {
    experimental_vcs: {
      initialize: ({siteDir}) => {
        // You can initialize and cache VCS data here, if needed
      },
      getFileCreationInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
      getFileLastUpdateInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
    },
  },
};

We have also noticed that our historical strategy to read from the Git history can be a significant build performance bottleneck for large Docusaurus sites. Issuing one git log \<filepath> call per MDX file doesn't scale well.

To solve this bottleneck, we implemented a strategy that reads the whole Git repository eagerly in a single git log call, leading to significant performance improvements. This strategy is now part of Docusaurus Faster (future.faster.gitEagerVcs: true) and will become the default in Docusaurus v4.

We also provide built-in VCS preset strategies. The available presets are:

• git-ad-hoc: the historical strategy based on git log \<filename> calls
• git-eager: the new Git strategy that reads your whole repository upfront
• hardcoded: returns a hardcoded value, useful in dev/tests to speed up DX
• disabled: returns null for all files, considering them untracked
• default-v1: the historical default (dynamic, git-ad-hoc in prod, hardcoded in dev)
• default-v2: the upcoming Docusaurus v4 default (dynamic, git-eager in prod, hardcoded in dev)

docusaurus.config.ts

export default {
  future: {
    experimental_vcs: 'default-v2',
  },
};

实验性功能

The VCS API is experimental and its design may change. If you give it a try, please share feedback on this community discussion.

Although the API may change, we consider the built-in Git Eager strategy stable for simple Git repositories. There may be edge cases with multiple nested Git repositories or submodules.

Translations

• 🇵🇰 #11632: Add new Urdu ur theme translations.
• 🇧🇷 #11533: Complete missing Brazilian Portuguese pt-BR theme translations.

其他改变：

Other notable changes include:

• In #11843, we now use TypeScript 6.0 for newly initialized sites. However, it requires "ignoreDeprecations": "6.0" for now.
• In #11571, the siteConfig.headTags API now accepts custom HTML elements.
• In #11675, the live code block theme now has a button to reset the playground.
• In #11734, we split the \<DocCard> component to make it easier to extend/swizzle. It's now easier to assign custom emojis for the docs generated index page.
• In #11733, the \<Tabs> component now uses React context instead of props, making it possible to create custom \<TabItem> components.
• In #11696, all newly initialized TypeScript sites will have "strict: true" by default.
• In #11611, we made it possible to create a new Docusaurus site in ., the current directory.
• In #11666, the pages plugin can now use Markdown file path links ([text](./other-page.md)), as the docs and blog plugins already support it.
• In #11642, admonitions now support class/id shortcuts, such as :::note{.my-class #my-id}.
• In #11541 and #11683, we made sure Docusaurus is compatible with the latest version of Algolia DocSearch 4.x, unlocking new features such as AskAI Suggested Questions.
• In #11684 and #11653, we removed many third-party dependencies from our create-docusaurus CLI, making it faster to create a new site.
• In #11794, we fixed a long-standing bug that prevented the translation of category index page titles in pagination links.
• In #11784, we changed the syntax we recommend for math equations, preferring regular Markdown code blocks over $$ to improve docs portability.
• In #11753, we added a basic AGENTS.md file. As a reminder, any AI usage in Docusaurus contributions must be disclosed.
• In #11698, we upgraded our monorepo to React 19. We'll drop support for React 18 in Docusaurus v4.

Check the 3.10.0 changelog entry for an exhaustive list of changes.