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

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

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

v4 Future 标志​

The Docusaurus v4 Future Flags let you opt in for upcoming Docusaurus v4 breaking changes incrementally and prepare for Docusaurus v4 ahead of time. You can enable them all at once with 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.

Security​

npm supply chain attacks have surged recently. A single compromised maintainer or package can ripple through the ecosystem and affect thousands of downstream users, as seen with the axios compromise.

We’ve taken steps to strengthen our supply chain, and recommend securing your own site with additional measures as well.

Trusted Publishing​

We adopted npm Trusted Publishing for stable and canary releases.

Releases are now published through a single publish.yml GitHub Actions workflow using short-lived OIDC tokens. Each release has verifiable provenance, with a transparency log showing how and when it was published.

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

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:

minimumReleaseAge: 10080

blockExoticSubdeps: true

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

trustPolicy: no-downgrade
trustPolicyExclude:
  - 'detect-port@1.6.1'
  - 'semver@6.3.1'

# 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:

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

Site Storage - Stable​

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

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

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.

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:

 # 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:

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)

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

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.

This release drops support for Node.js 18, adds support for Algolia DocSearch v4 with AskAI, improves i18n support, adds Mermaid ELK layout support, and comes with various other improvements and bug fixes.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, accordingly to our release process. Note that we consider dropping End-of-Life Node.js versions as non-breaking changes.

Dropping Node.js 18​

In #11408, we have dropped support for Node.js 18, and the new minimum required Node.js version is now v20.0.

Although it may look like a runtime requirement breaking change, Node.js 18 reached End-of-Life. It won't receive security updates, and you shouldn't use it anymore. Dropping End-of-Life versions of Node.js on minor version releases is a common practice in the Node.js ecosystem, that we now officially endorse and document on our release process.

This upgrade is further motivated by our dependencies:

• Some of our dependencies now only receive security patches on newer versions that do not support Node.js 18 anymore. See, for example, this webpack-dev-server@4 security warning. To keep the Docusaurus v3 release line secure for our users, for both the runtime and third-party dependencies, the upgrade is necessary.
• Some of our dependencies are also dropping support for Node.js 18 in minor releases, transitively impacting Docusaurus runtime requirements. For example, Rspack 1.5 now requires Node.js 18.12, while Docusaurus v3 initially supported Node.js 18.0.

DocSearch v4​

In #11327 and #11421, we added support for Algolia DocSearch v4. This new version comes with AskAI support, letting you add an AI-powered search assistant to your Docusaurus site that can answer questions based on what's in your documentation with a conversational experience.

http://localhost:3000/

i18n improvements​

In #11316, we added new i18n.localeConfigs[locale].{url,baseUrl} config options to better support complex and multi-domain i18n deployments. Previously, Docusaurus relied on hard-coded heuristics that made sense for most i18n projects, but weren't flexible enough to accommodate all use cases, leading UX and SEO issues. It is now possible to configure each locale's deployment URL and base URL independently, overriding the default values inferred by Docusaurus:

export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    localeConfigs: {
      en: {
        url: 'https://en.docusaurus.io',
        baseUrl: '/',
      },
      fr: {
        url: 'https://fr.docusaurus.io',
        baseUrl: '/',
      },
    },
  },
};

In #11304, we optimized our i18n infrastructure with a new i18n.localeConfigs[locale].translate flag that is now false by default for sites that do not use any translations. This leads to an improved dev experience and faster builds for non-i18n sites by avoiding unnecessary file system read attempts of the i18n directory.

In #11228, we added a new key attribute to the docs sidebar items, allowing to assign explicit translation keys to each sidebar item that use the same label and would otherwise lead to translation key conflicts:

export default {
  sidebar: [
    {
      type: 'category',
      label: 'API',
      key: 'api-for-feature-1',
      items: [],
    },
    {
      type: 'category',
      label: 'API',
      key: 'api-for-feature-2',
      items: [],
    },
  ],
};

Mermaid ELK layouts​

In #11357, we added support for Mermaid ELK layout algorithm, based on the Eclipse Layout Kernel (ELK). Compared to the default Dagre layout, it provides more sophisticated layout capabilities and configuration options, especially useful when working with large or intricate diagrams.

You can enable it by adding the extra @mermaid-js/layout-elk npm dependency, making it possible to use the layout: elk Mermaid diagram metadata:

```mermaid
---
config:
  layout: elk
---
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

Translations​

• 🇧🇷 #11315: Add missing Brazilian Portuguese theme translations.
• 🇺🇦 #11305: Add missing Ukrainian theme translations.

其他改变：​

Other notable changes include:

• In #11283, we added siteConfig.markdown.hooks.{onBrokenMarkdownLinks,onBrokenMarkdownImages} and deprecated siteConfig.onBrokenMarkdownLinks. The new callback hooks also let you recover from broken links/images by returning a fallback URL.
• In #11282, we added the siteConfig.markdown.emoji config option to disable the previously hard-coded remark-emoji behavior.
• In #11397, we can now resolve site-aliased Markdown links starting with @site/*, that we already supported for ES imports.
• In #11294 and #11415, we upgraded to Rspack 1.5 and leveraging new Rspack config options to make Docusaurus build faster.
• In #11356, we improved the display of docs sidebar items with long labels.
• In #11405, we improved visual glitches caused by the useColorMode() hook when switching color modes, glitches that also affected your site's logo in the navbar.
• In #11383, we disabled a Docusaurus Faster HTML minifier optimization that prevents your site's social card from displaying properly on some social platforms (e.g., LinkedIn).
• In #11425, we added the ability for blog authors to display an email icon with a mailto: link (author.socials.email).
• In #11422, we removed the copy-text-to-clipboard in favor of the native navigator.clipboard API.

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

This release improves build performance, includes new features and introduces "Future Flags" to prepare your site for Docusaurus 4.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, accordingly to our release process.

Performance​

This release keeps improving our build infrastructure performance with various optimizations, and 2 new Docusaurus Faster options.

Docusaurus Faster​

Docusaurus Faster has been introduced in Docusaurus v3.6, and permits you to opt-in for our upgraded build infrastructure and helps you build your site much faster. The experimental flags can be turned on individually, but we recommend to turn them all at once with this convenient shortcut:

const config = {
  future: {
    experimental_faster: true,
  },
};

Persistent Cache​

In #10931, we have enabled the Rspack persistent cache. Similarly to the Webpack persistent cache (already supported), it permits to greatly speed up the bundling of the Docusaurus app on subsequent builds.

In practice, your site should build much faster if you run docusaurus build a second time.

This feature depends on using the Rspack bundler, and can be turned on with the rspackPersistentCache flag:

const config = {
  future: {
    experimental_faster: {
      rspackBundler: true, // required flag
      rspackPersistentCache: true, // new flag
    },
  },
};

Result: On average, you can expect your site's bundling time to be ~2-5× faster on rebuilds 🔥. The impact can be even more significant if you disable the optional concatenateModule optimization.

Worker Threads​

In #10826, we introduced a Node.js Worker Thread pool to run the static side generation code. With this new strategy, we can better leverage all the available CPUs, reduce static site generation time, and contain potential memory leaks.

This feature can be turned on with the ssgWorkerThreads flag, and requires the v4.removeLegacyPostBuildHeadAttribute Future Flag to be turned on:

const config = {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true, // required
    },
    experimental_faster: {
      ssgWorkerThreads: true,
    },
  },
};

Result: On average, you can expect your site's static site generation time to be ~2× times faster 🔥. This was measured on a MacBook Pro M3 and result may vary depending on your CI.

Other Optimizations​

We identified and resolved several major bottlenecks, including:

• In #11007, we optimized the dev server startup time for macOS users. We figured out that the code to open your browser used expensive synchronous/blocking calls that prevented the bundler from doing its work. From now on, the bundler and the macOS browser opening will run in parallel, leading to a faster docusaurus start experience for all macOS users.
• In #11163, we noticed that the docs showLastUpdateAuthor and showLastUpdateTime are quite expensive, and require to run a git log command for each document. On large sites, running these commands in parallel can exhaust the system and lead to Node.js EBADF errors. We implemented a Git command queue to avoid exhausting the system, which also slightly increased performance of our plugin's loadContent() lifecycle.
• In #10885, we implemented an SVG sprite for the external link icon. Due to its repeated appearance in various places of your site (navbar, footer, sidebars...), using a React SVG component lead to duplicated SVG markup in the final HTML. Using a sprite permits to only embed the icon SVG once, reducing the generated HTML size and the static generation time. We plan to use more SVG sprites in the future.
• In #11176, we fine-tuned the webpack/Rspack configuration to remove useless optimizations.

Impact​

We have upgraded the React Native website to Docusaurus v3.8 already. Here's an updated benchmark showing the global Docusaurus Faster impact on total build time for a site with ~2000 pages:

We measured similar results on our website:

You can also expect memory usage improvements, and a faster docusaurus start experience.

Future Flags​

The Docusaurus v4 Future Flags let you opt-in for upcoming Docusaurus v4 breaking changes, and help you manage them incrementally, one at a time. Enabling all the future flags will make your site easier to upgrade to Docusaurus v4 when it's released.

const config = {
  future: {
    v4: true,
  },
};

CSS Cascade Layers​

In Docusaurus v4, we plan to leverage CSS Cascade Layers. This modern CSS feature is widely supported and permits to group CSS rules in layers of specificity. It is particularly useful to give you more control over the CSS cascade. It makes the CSS rules less dependent on their insertion order. Your un-layered rules will now always override the layered CSS we provide.

In #11142, we implemented a new experimental @docusaurus/plugin-css-cascade-layers that you can turn on through the v4.useCssCascadeLayers flag if you use the classic preset:

export default {
  future: {
    v4: {
      useCssCascadeLayers: true,
    },
  },
};

We consider this feature as a breaking change because it can slightly alter the CSS rules application order in customized sites. These issues are usually limited, and relatively easy to fix (see for example the React Native CSS changes). Sites that do not provide custom CSS and do not swizzle any component should not be affected.

In practice, it permits to automatically apply built-in CSS Cascade Layers to all the CSS we provide, including our opinionated CSS framework Infima:

@layer docusaurus.infima {
  h1 {
    /* Infima css rules */
  }
  pre {
    /* Infima css rules */
  }
}

Layers can help solves our long-standing Global CSS pollution issue. Our built-in global CSS rules may conflict with yours, making it harder to use Docusaurus to create playgrounds, demos and embedded widgets that are isolated from our CSS. Thankfully, CSS Cascade Layers can be reverted to create HTML subtrees that are not affected by the CSS Docusaurus provides.

/* The "impossible" :not() selector helps increase the specificity */
.my-playground:not(#a#b) {
  &,
  * {
    @layer docusaurus.infima {
      all: revert-layer;
    }
  }
}

postBuild() Change​

In #10850, we added a new removeLegacyPostBuildHeadAttribute Future Flag that slightly changes the signature of the postBuild() plugin lifecycle method, removing the head attribute.

export default {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
  },
};

This legacy data structure is coming from our react-helmet-async dependency and should have never been exposed as public API in the first place. It is not serializable, which prevents us from implementing Worker Threads for the static site generation.

While technically a breaking change, we believe this change will not affect anyone. We couldn't find any open source plugin that uses the head parameter that this method receives. If turning this flag on breaks your site, please let us know here.

System Color Mode​

In #10987, the classic theme now lets you revert the color mode to the system/OS value.

Code Block Refactor​

In #11058, #11059, #11062 and #11077, the theme code block components have been significantly refactored in a way that should be much easier to swizzle and extend.

According to our release process, this is not a breaking change, but sites that have swizzled these components may need to upgrade them.

Translations​

• 🇹🇷 #10893: Add missing Turkish theme translations.
• 🇵🇱 #10884: Add missing Polish theme translations.
• 🇨🇳 #10816: Add missing Chinese theme translations.
• 🇯🇵 #11030: Add missing Japanese theme translations.

维护​

Docusaurus 3.8 is ready for Node.js 24 and TypeScript 5.8.

We also removed useless npm packages and internalizing unmaintained ones:

• In #11010 and #11014, we internalized the unmaintained react-ideal-image and react-waypoint package used in @docusaurus/plugin-ideal-image, and made them compatible with React 19.
• In #10956, we removed our dependency to the unmaintained react-dev-utils package (from Create-React-App).
• In #10358, we replaced the unmaintained shelljs package by execa
• In #11138, we removed the reading-time package in favor of the built-in Intl.Segmenter standard API to compute blog post reading times.
• In #11037, we removed the useless clean-webpack-plugin.

其他改变：​

Other notable changes include:

• In #10852, the theme docsVersionDropdown navbar item now accepts a versions attribute.
• In #10953, the @docusaurus/remark-plugin-npm2yarn plugin now supports Bun tabs conversions by default.
• In #10945, more stable CSS classes are now applied to the main theme layout elements, to let you create more reliable CSS selectors.
• In #10846, the Markdown code block showLineNumbers metastring can now accept a number to initialize the line counter initial value.
• In #11090, we made it easier to provide a custom page title formatter.
• In #11088, the page plugin now supports frontMatter.slug like docs and blog plugins already do.
• In #10875, the docs versioning CLI now also copies localized docs JSON translation files.

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

Docusaurus 现已完全兼容 React 19。

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

精彩内容​

React 19​

在 #10763 这一个更新中，我们添加了对 React 19 的支持，Docusaurus 网站已经在 React 19 上运行。

从现在起，所有新初始化的站点默认都会在 React 19 上运行，Docusaurus v4 的最低要求版本将是 React 19 。

不过，React 18 仍然能够得到支持，现有的 Docusaurus 站点可以选择留在React 18，或者将其依赖升级到 React 19：

{
  "name": "my-docusaurus-site",
  "dependencies": {
-   "react": "^18.0.0",
-   "react-dom": "^18.0.0"
+   "react": "^19.0.0",
+   "react-dom": "^19.0.0"
  }
}

Along the way, we fixed all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings.

SVGR 插件​

Docusaurus 内置支持 SVGR，允许您将 SVG 文件作为 React 组件无缝导入并使用：

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

This built-in support has been the source of various bug reports due to the inability to customize the SVGR Options, in particular the SVG Optimizer options.

In #10677, we extracted a new @docusaurus/plugin-svgr that you can now configure according to your needs. 默认情况下它包含在我们经典预设中：

export default {
  presets: [
    [
      'classic',
      {
        svgr: {
          svgrConfig: {
            // 您的 SVGR 选项...
            svgoConfig: {
              // 您的 SVGO 选项...
              // Use "svgoConfig: undefined" to use a svgo.config.js file
            },
          },
        },
      },
    ],
  ],
};

其他改变：​

Other notable changes include:

• #10768: Blog authors have built-in icons for social platforms bluesky, mastodon, threads, twitch, youtube, instagram.
• #10729：博客现在支持 frontMatter.sidebar_label
• #10803: @docusaurus/remark-plugin-npm2yarn 现在支持 Bun 转换
• #10672：将 Algolia DocSearch 升级到 algoliasearch v5
• #10800: Docusaurus Faster turns Rspack incremental mode on by default.
• #10783：改进荷兰语的主题翻译
• #10760：改进韩文的主题翻译

查看 3.7.0 changelog entry 以获取更详细的变更列表

Docusaurus 现在可以⚡️⚡️⚡️: 更快的 构建你的网站。

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

精彩内容​

该版本主要专注于通过 Docusaurus Faster 项目构建性能。

Docusaurus Faster​

Docusaurus Faster项目的目标是减少构建时间和内存消耗。

我们致力于多个优化和使我们的基础设施现代化，以便更快地使用基于Rus的工具，特别是：

• 🦀 Rspack: 基于Rust的快速网页打包工具, 几乎是可以作为 webpack的完全替代品
• 🦀 SWC: 快速的网页编辑器，基于Rust的网页平台(HTML, CS, JS)
• 🦀 Lightning CSS: 一个极为快速的 CSS 解析器、翻译器、打包工具和压缩器。

影响​

采用新的基础设施可能会产生各种影响。 由于不可能将所有问题全部列举出来，因此我们将重点关注主要的几个。

为了帮助您轻松地使用它，我们在预期的静态站点输出和浏览器支持 方面相当保守。

构建时间​

社区网站上的基准测试显示，您可以期待您的生产网站构建速度 ⚡️ 提高 2 到 4 倍！ 🔥:

• React Native website: 速度提升了 3.04x 倍 🔥
• Babel website: 速度提升了 3.27x 倍 🔥
• Lexical website: 速度提升了 2x 倍 🔥

如何进行基准测试

内存消耗​

您还应该注意到内存消耗的改进：

• 新基础设施消耗总内存减少
• 我们修复了一个重要的内存泄漏，它特别影响到i18n 站点
• 我们添加了CI检查，以确保我们不会出现回归问题，并且我们的站点和初始化模版都能在内存受限的环境中构建。
• 我们添加了内部工具以更好地理解构建的哪一步消耗内存
• 我们移除了一个 process.exit(0)，该代码可能会掩盖您自己代码和第三方插件中的内存泄漏问题。

其他影响​

• HTML 压缩器现在可以在出现无效的 HTML markup时发出警告
• 静态 HTML 输出 减少了~5%的大小
• 一些错误被新的基础结构自动修复

采用策略​

这种新的基础设施是一种突破性的变化，但它是选择性的，不需要新版本的Docusaurus。

在使用 Docusaurus 更快之前，添加这个新包：

npm install @docusaurus/faster

yarn add @docusaurus/faster

pnpm add @docusaurus/faster

bun add @docusaurus/faster

为了帮助您在 在Docusaurus v3中逐步采用它，我们引入了一组可以逐步激活的功能标志。

我们建议通过这个简单的布尔快捷方式一次性启用它们：

const config = {
  future: {
    experimental_faster: true,
  },
};

如果其中一个功能标志不适用于您的网站，可以独立启用功能标志：

const config = {
  future: {
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      mdxCrossCompilerCache: true,
    },
  },
};

• swcJsLoader: 使用 SWC 转换JS(而不是 Babel)
• swcJsLoader: 使用 SWC 转换JS(而不是 Babel)
• swcHtmlMinimizer : 使用 SWC 来挖掘HTML和嵌入式JS/CSS(而不是 html-minifier-terser)
• lightningCssMinimizer：使用 Lightning CSSS 来缩小CSS (而不是 cssnano 和 clean-css)
• rspackBundler：使用 Rspack 打包您的应用程序(而不是 webpack)
• mdxCrossCompilerCache：一次同时为浏览器/Node.js环境编译MDX文件，而不是两次。

插件​

新的基础设施使用 Rspack。 碰巧的是，Rspack 与 webpack 几乎 100% 兼容，并且 Rspack 不会破坏我们的插件生态系统。

大多数Docusaurus插件都应该可以与Rspack开箱即用，即使是那些实现了configureWebpack 的插件。

然而，其中有些需要做小的修改，以使其与Rspack兼容。 一般的想法是避免直接导入 webpack ，而是使用 "动态提供" webpack 实例：

-import webpack from 'webpack';

export default function (context, options) {
  return {
    name: 'custom-docusaurus-plugin',
-   configureWebpack(config, isServer) {
+   configureWebpack(config, isServer, {currentBundler}) {
      return {
        plugins: [
-         new webpack.DefinePlugin({}),
+         new currentBundler.instance.DefinePlugin({}),
        ]
      };
    },
  };
}

后续步骤​

这是一个开端：我们将继续开发Docusaurus Faster项目，并且已经计划了一些更多的性能改进。

取决于您的反馈, 我们计划在即将到来的主要版本Docusaurus中将此新基础设施设置为默认。

🙏 我们感谢所有这些伟大工具的作者，这些工具已经帮助我们使Docusaurus比以前快得多。 特别感谢 Rspack 团队 在整个过程中对我们的支持，他们迅速处理了我们的反馈，并现了我们所需的所有缺失功能，使这一切得以顺利进行。 👏

Rsdoctor 插件​

在 #10588中, 我们创建了一个 Rsdoctor的Docusaurus插件. 它分析了 Docusaurus 的打包阶段，帮助你找出在加载器、插件和压缩器方面导致打包速度变慢的原因。 它同时适用于webpack 和 Rspack。

要使用它，请安装新的 @docusaurus/plugin-rsdoctor 包，然后在你的配置中使用插件：

export default {
  plugins: [
    [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};

export default {
  plugins: [
    process.env.RSDOCTOR === 'true' && [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};

# Build without Rsdoctor
npm run build

# Build with Rsdoctor
RSDOCTOR=true npm run build

Mermaid​

在 #10510 中，我们放宽了我们的 Mermaid diagrams 依赖范围以允许较新的主要版本的Mermaid。 我们现在支持 Mermaid 10 和 11，并预计即将发布的版本也将兼容，让您可以根据自己的需求进行升级。

解锁了新的图表类型，例如 架构图：

Translations​

• 🇸🇮 #10551: 改进斯洛文尼亚语翻译。
• :越南：#10507：改进越南主题翻译。
• 🇪🇸 #10413: 改进西班牙语主题的翻译。

其他改变：​

Other notable changes include:

• #10586: 博客支持 frontMatter.title_meta 以基于SEO 的理由覆盖 frontMatter.title 。
• #10600: docusaurus build and docusaurus depl 现在支持多个--locale CLI args.
• #10454: docusaurus-mot-plugin-npm2yarn 升级到 [npmto-yarn v3](https://github.com/nebrelbug/npm-to yarn/releases/tag/v3.0.0.0) 并可以转换 npx 命令。
• #10612：Canary releases will used 3.5.2-canary-<number> 而不是0.0.0-canary-<number> for respect plugins peerDependency。
• #10547: @docusaurus/tsconfig 升级到 `target: 'es2022'
• #10514：从Docusaurus init 模板中删除babel.config.js，以阻止定制Babel。

查看 3.6.0 changelog entry 以获取更详细的变更列表

This release contains many new exciting blog features.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

精彩内容​

Blog Social Icons​

In #10222, we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the authors.yml file.

slorber:
  name: Sébastien Lorber
  # other author properties...
  socials:
    x: sebastienlorber
    linkedin: sebastienlorber
    github: slorber
    newsletter: https://thisweekinreact.com

Icons and handle shortcuts are provided for pre-defined platforms x, linkedin, github and stackoverflow. It's possible to provide any additional platform entry (like newsletter in the example above) with a full URL.

Blog Authors Pages​

In #10216, we added the possibility for global blog authors (declared in authors.yml) to have their own dedicated page listing all the blog posts they contributed to.

This feature is opt-in and mostly relevant for multi-author blogs. You can turn it on for a specific author by setting the page: true property:

slorber:
  name: Sébastien Lorber
  # the description will be displayed on the author's page
  description: 'A freelance React and React-Native developer...'
  page: true # Turns the feature on

This creates a dedicated author page at /blog/authors/slorber.

An authors index page is also created, listing all the blog authors.

Check the blog authors pages guide for details.

Blog Feeds Styling​

In #9252, we added support for styling your blog feeds by providing custom XSLT .xls files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view.

const blogOptions = {
  feedOptions: {
    xslt: {
      rss: 'custom-rss.xsl',
      atom: 'custom-atom.xsl',
    },
  },
};

Writing your own XSLT can be complex, but you can also use xslt: true to turn on the built-in style:

const blogOptions = {
  feedOptions: {
    xslt: true,
  },
};

Blog Sidebar Grouping​

In #10252, we added support for grouping blog posts by years in the blog sidebar.

This feature is now turned on by default, but can be disabled with themeConfig.blog.sidebar.groupByYear: false.

Blog Consistency Options​

We added new blog options to enforce recommended practices for your blog posts:

onInlineAuthors​

We believe large multi-blogs are easier to manage by using global authors, declared in authors.yml. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate author pages.

In #10224, we added the onInlineAuthors option. Use onInlineAuthors: 'throw' to forbid inline authors, and enforce a consistent usage of global authors.

onUntruncatedBlogPosts​

We believe blog posts are better using truncation markers (<!-- truncate --> or {/* truncate */}). On paginated lists (blog home, tags pages, authors pages), this permits to render a more concise preview of the blog post instead of a full blog post.

In #10375, we added the onUntruncatedBlogPosts option. Use onUntruncatedBlogPosts: 'throw' to enforce a consistent usage of truncation markers.

Translations​

• 🇪🇪 #10339: Add Estonian theme translations.
• 🇮🇩 #10325: Add Indonesian theme translations.
• 🇪🇸 #10360: Improve Spanish theme translations.
• 🇩🇪 #10235: Improve German theme translations.
• 🇨🇳 #10257: Improve Traditional Chinese (zh-Hant) theme translations.

其他改变：​

Other notable changes include:

• #10369: Add support for pkg.pr.new continuous releases so that you can test any pull-request code in a StackBlitz playground.
• #10376: Theme unlisted/draft banners are also shown in dev so that you don't forget to publish your content.
• #10335: The Markdown top-level headings # title are automatically wrapped in <header> for consistency with front matter title: Title.
• #10286: Allows Docusaurus plugins to self-disable by returning null.
• #10241: Add support for MDX processor recmaPlugins option to modify the MDX Estree AST.
• #10324: The docs autogenerated _category_.json accepts a new description property that gets displayed on generated index pages.
• #10368: The CLI command docusaurus --version now actually returns the Docusaurus version.
• #10240: Markdown mdx-code-block now supports indentation.
• #10219: Fix <TabItem lazy> support the for className prop.
• #10313: Blog-related @docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-blog/client.
• #10316: Docs-related @docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-docs/client.

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

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

精彩内容​

Tags files​

The docs and blog plugins both already supported a tags front matter attribute, enabling you to group related content. But tags declared inline in the front matter are not always ideal.

With #10137, you can now declare a list of pre-defined tags in a tags.yml file:

tag1:
  label: 'Tag 1'
  description: 'Tag 1 description'
  permalink: /tag-1-permalink

tag2:
  label: 'Tag 2'
  description: 'Tag 2 description'
  permalink: /tag-2-permalink

These predefined tags can be used in the front matter of your blog or docs files:

---
tags: [tag1, tag2]
---

# Title

Content

Hash Router - Experimental​

With 9859, we added a new experimental hash router config option, useful for offline browsing by opening your site locally through the file:// protocol.

export default {
  future: {
    experimental_router: 'hash',
  },
};

When this mode is turned on, Docusaurus will opt out of static site rendering, and build a client-side single page application where all routes are prefixed with /#/. A single index.html file is generated. This file can be opened locally in your browser by simply clicking it, using the browser file:// protocol. This makes it possible to distribute a Docusaurus site as a .zip file so that readers can browse it offline, without having to install anything complex on their computer apart a web browser.

Try browsing our own Docusaurus site built with the hash router:

• Docusaurus website - Hash Router web deployment
• Docusaurus website - Hash Router downloadable GitHub artifacts

Site Storage - Experimental​

Docusaurus uses the browser localStorage API to persist UI state.

But sometimes the storage space is "shared" between multiple sites using the same domain, leading to storage key conflicts. This generally happens in two cases

• when working on multiple http://localhost:3000 sites
• when hosting multiple sites under the same domain: https://example.com/site1/ and https://example.com/site2/

For this reason, we introduced a new experimental siteStorage configuration option:

export default {
  future: {
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
  },
};

When namespace: true is set, we apply a hash suffix to all the storage keys, making them unique to the current site (based on config.url and config.baseUrl. For example, the theme storage key becomes theme-x6f. It is also possible to provide your own custom suffix namespace: 'suffix'. We also made it possible to use type: 'sessionStorage' instead of the default localStorage.

其他改变：​

Other notable changes include:

• #10151: add Turkmen (tk) theme translations
• #10111: add Bulgarian (bg) theme translations
• #10168: fix many long overdue Markdown link resolution bugs
• #10178: the /search page now respects the contextualSearch: false setting
• #10118: fix bad pluralization on docs generated index category card description
• #10130: fix false positives reported by the broken anchor checker due to trailing slashes

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

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

精彩内容​

Prepare for React 19​

The React core team recently released the first React 19 beta. They also published an upgrade guide and a React v18.3 release with new warnings to help us identify issues before upgrading to React 19.

Docusaurus v3 depends on React 18.x. When initializing a new Docusaurus sites, it will use that new React 18.3 release. It's also the case if you decide to upgrade your dependencies, or re-generate your package manager lockfile.

It turns out in its current state, Docusaurus had a few of those extra warnings to fix, notably this one immediately appearing on your dev console on any page load and navigation:

Warning: LoadableComponent uses the legacy contextTypes API which is no longer supported and will be removed in the next major release. Use React.createContext() with static contextType instead.

In #10079, we got Docusaurus ready for React 19. We fixed all the React 18.3 warnings we encountered. In case we missed any, don't hesitate to report new warnings if you see them, to us but also to other Docusaurus third-party plugin authors.

createSitemapItems​

In #10083, we introduced a new flexible createSitemapItems() hook to the sitemap plugin. This enables users to create/filter/transform/enhance the sitemap items with their own custom logic.

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        sitemap: {
          createSitemapItems: async ({
            defaultCreateSitemapItems,
            ...params
          }) => {
            const items = await defaultCreateSitemapItems(params);
            return items.filter((item) => !item.url.includes('/tags/'));
          },
        },
      },
    ],
  ],
};

Pages plugin improvements​

The Docusaurus pages plugin has historically been lagging behind the docs and blog plugins in terms of available feature.

In #10032 we normalized the options available on each core content plugins by adding a few the missing page plugins APIs related to the edit url and the last update metadata displayed at the bottom on Markdown pages.

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        pages: {
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/website/src/pages',
          editLocalizedFiles: true,
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
        },
      },
    ],
  ],
};

其他改变：​

Other notable changes include:

• #10064: new site config option siteConfig.markdown.anchors.maintainCase
• #9767: new docusaurus deploy --target-dir option
• #10042: new (experimental) plugin API: route.props
• #10060: optimizes the App entrypoint, avoid useless re-renders on navigations
• #10080: <Admonition> component can render properly without heading/icon
• #10091: <Tabs> props can now override defaults
• #10090: docusaurus serve works better with a /baseUrl/ pathname prefix
• #10070: add missing theme translations for pt-BR
• #10025: doc sidebar item label now impacts the doc pagination label

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

The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.

精彩内容​

Faster builds​

We worked hard to reduce the time it takes to build a Docusaurus site in production mode.

Between v3.1.0 and v3.2.0, several changes have been made, leading to significantly faster production builds for many sites.

Let's take an example. Our benchmark on the React Native website upgrading to v3.2 reports the following results:

• 🔥 Cold builds: 95s ➡️ 66s (~30% faster)
• 🔥 Incremental builds: 55s ➡️ 22s (~60% faster)

The results will vary depending on your site's topology and the options you turned on, but we expect the largest sites will see the most significant improvements.

Note that this is only the beginning, and Docusaurus performance can still be significantly improved, notably the bundling time and the memory consumption. Track our performance issue for upcoming improvements.

Faster Dev Server​

We also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files.

The way we initially implemented content reloading wasn't great. For example, editing a blog post file would also trigger a useless reload of the unrelated docs plugin. From now on, when editing a plugin's content, only that plugin will reload. It's hard to measure precisely the impact of this change, but I estimate edits should appear in your browser at least 50% faster 🔥.

We plan to keep improving the speed of our dev server, with even more granular hot reloads, ensuring we don't run useless computations that would always keep giving the same result.

MDX partials table-of-contents​

With #9684, Docusaurus is now able to render headings coming from an imported partial into the table-of-contents.

Docusaurus and MDX allows you to import one Markdown file into another. We usually call the imported Markdown file a "partial", and use the _ prefix so that this file does not lead to the creation of a new page.

# My Doc

## Doc heading

Content is imported from another MDX file:

import ImportedDoc from './\_importedDoc.mdx';

<ImportedDoc />

## Partial heading

Some paragraph

Previously, the heading Partial heading did not appear in the table-of-contents, but now it will!

Blog improvements​

We improved the blog plugin with several new options to make it even more powerful and flexible:

• #9912: you can now display the last update time and author of a blog post, a feature the docs plugin already had.
• #9886: a new processBlogPosts option allow you to filter/transform/sort blog posts.
• #9838: a new pageBasePath option allows you to customize the blog pagination URL segment (/blog/page/2)

Sitemap lastmod​

With #9954, the sitemap plugin has a new lastmod option that can now emit a <lastmod> tag on the XML. The value is read from the Git history by default, but can be overridden with docs and blog last_update front matter.

We also made it possible to opt-out of emitting <priority> and <frequency> tags, which are generally ignored by crawlers (notably Google).

We recommend using the following sitemap plugin config, that will become the default in Docusaurus V4:

{
  lastmod: 'date',
  priority: null,
  changefreq: null,
}

其他改变：​

• #9687: new Vercel Analytics plugin
• #9681 and #9442: docusaurus swizzle and create-docusaurus CLIs now ask users if they prefer to use TypeScript
• #9928: new Icelandic translation
• #9928: new allContentLoaded plugin lifecycle (experimental)

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

The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.

精彩内容​

Broken anchors checker​

In #9528, we improved the built-in broken links checker to also detect broken anchors.

parseFrontMatter hook​

In #9624, we added a new siteConfig.markdown.parseFrontMatter function hook.

This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.

export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

Read the front matter guide and the parseFrontMatter API ref for details.

其他改变：​

Other notable changes include:

• #9674: add siteConfig.markdown.remarkRehypeOptions to pass options to remark-rehype, letting you customize things such as MDX footnote label
• #9671: add code block MagicComments support for (Visual) Basic/Batch/Fortran/COBOL/ML
• #9610: enable CLI port configuration via PORT environment variable
• #9477: complete Brazilian Portuguese (pt-BR) translations

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

At Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content.

This is a new major version of Docusaurus, coming with new exciting features and upgraded dependencies.

In line with the Semantic Versioning principles, this release includes breaking changes we documented thoroughly in the v3 upgrade guide. Breaking changes can be bothersome, but they are necessary to set the ground for a new wave of Docusaurus features we plan to implement.

We initially planned to release more frequent major versions, but Docusaurus v3 has taken longer than expected. Among the breaking changes that we accrued, upgrading to MDX v3 is probably the main challenge to the adoption of this new version. We went the extra mile to make this upgrade as easy as possible, notably by adding compatibility options for MDX v1.

The simplest sites will only need to upgrade a few npm dependencies. For more complex sites, we came up with a few strategies that can help you upgrade more confidently:

• Prepare your site ahead of time, incrementally, while staying on Docusaurus v2
• Set up visual regression tests to catch unexpected visual changes happening during the upgrade

Breaking changes​

This section only gives you a quick glance. All the breaking changes are thoroughly documented in the v3 upgrade guide.

Docusaurus v3 upgraded a few dependencies to new major versions, each coming with its own breaking changes:

• Node.js v16 ➡️ v18
• React v17 ➡️ v18
• MDX v1 ➡️ v3
• TypeScript v4 ➡️ v5
• prism-react-renderer v1 ➡️ v2
• react-live v2 ➡️ v4
• Mermaid v9 ➡️ v10
• import-fresh v3 ➡️ jiti v1
• remark-emoji v2 ➡️ v4

A typical package.json dependency upgrade looks like:

 {
   "dependencies": {
     // upgrade to Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // upgrade to MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // upgrade to prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // upgrade to React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // upgrade Docusaurus dev dependencies to v3
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@docusaurus/types": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/types": "3.0.0"
   }
   "engines": {
     // require Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

Apart from MDX v3, most breaking changes coming with those upgraded dependencies have been handled internally for you: most of the time, you shouldn't have to do anything. Outside of dependencies, the only functional breaking changes coming explicitly from the Docusaurus codebase are:

• #9189: new default blog RSS feed limit of 20 entries
• #9308: fix and re-introduce the :::warning admonition, deprecate :::caution
• #9310: remove the legacy versioned sidebar id prefix, used for sites versioned before v2.0.0-beta.10 (December 2021)
• #7966: refactor docs theme components, eventually requiring to you re-swizzle them

精彩内容​

Below is a non-exhaustive list of new useful features coming with this new version. All the features are listed in the Docusaurus v3.0.0 release notes.

Markdown​

Docusaurus v3 upgraded from MDX v1 to MDX v3:

• in #8288, we upgraded to MDX v2 (migration guide)
• in #9451, we upgraded to MDX v3 (migration guide)

This new MDX version is much better for content writers and plugin authors, and lays the ground for implementing new exciting Markdown features.

This notably enables us to add a CommonMark mode that should make it easier for existing documentations to adopt Docusaurus. It is currently opt-in and experimental and limited (some Docusaurus features will not work). In Docusaurus v3, all files are still interpreted as MDX, but we plan to interpret .md files as CommonMark in an upcoming major version, and recommend to use the .mdx extension for any file using JSX or ES modules.

We also introduced a new way to configure Markdown globally for your site, and plan to add more flexible options later.

export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Docusaurus now uses the remark-directive plugin to support admonitions. This also offers you the ability to create your own Remark plugins to extend Markdown with your own custom directives such as :textDirective, ::leafDirective or :::containerDirective.

ESM and TypeScript configs​

In #9317, we added support for ES Modules and TypeScript config files, including site config, docs sidebars, plugins and presets.

Here are 2 TypeScript examples, giving you a modern experience with IDE autocompletion:

import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',
  // your site config ...
  presets: [
    [
      'classic',
      {
        // your preset config ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // your theme config ...
  } satisfies Preset.ThemeConfig,
};

export default config;

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: ['introduction'],
};

export default sidebars;

Unlisted content​

Docusaurus already supported a draft: true front matter option in our 3 content plugins (docs, blog, pages), which allows you to remove some pages from your production builds.

In #8004, we introduced a new unlisted: true front matter option, which will keep your pages available in production builds, while "hiding" them and making them impossible to discover unless you have the url. This enables convenient workflows where you can easily ask for feedback on a piece of content before the final publication.

Unlisted content will:

• be excluded from sitemap.xml
• be excluded from SEO results thanks to <meta name="robots" content="noindex, nofollow" />
• be excluded from blog RSS feeds
• be excluded from Algolia DocSearch results
• be filtered from site navbar items, docs sidebars, blog sidebar, blog archives, tags pages...

Unlisted content will also display a banner so that you don't forget to turn it off once your content is ready for prime time. Here's an example of an unlisted blog post:

React 18​

In #8961, we upgraded to React 18. This is important, notably for the gradual adoption of Concurrent React features, as well as upcoming exciting features such as build-time React Server Components.

This new version of React should be a drop-in replacement for most Docusaurus sites. It comes with breaking changes that we handled internally in the Docusaurus codebase. If your site is using a lot of custom React code, we recommend you to take a look at the official article on How to Upgrade to React 18, notably the new automatic batching behavior.

Automatic JSX runtime​

Docusaurus now uses the "automatic" JSX runtime.

It is not needed anymore to import React in JSX files that do not use any React API.

- import React from 'react';

  export default function MyComponent() {
    return <div>Hello</div>;
  }

Debug builds​

It is now possible to build your static site in dev mode.

docusaurus build --dev

TypeScript​

Docusaurus v3 now requires a minimum version of TypeScript 5.0.

We re-internalized the base recommended TypeScript config to a new official package:

 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

We also have cleaner, normalized exports for Docusaurus core type, plugin, and preset options, which you can use within the brand-new TypeScript config files:

import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

代码块​

In #9316, we improved on syntax highlighting thanks to the prism-react-renderer v2 upgrade. For example, a bash param --save is now colored:

npm install --save some-package

The interactive code editor also upgrades to react-live v4, coming with a new sucrase compiler. It is faster, lighter, and supports modern features, notably TypeScript type annotations.

function Hello() {
  const name: string = 'World';
  return <div>Hello {name}</div>;
}

In #8982 and #8870, we also added magic comments support for TeX-like, Haskell-like, and WebAssembly comment syntax.

stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs

function result = times2(n)
  result = n * 2;
end
x = 10;
y = times2(x);

Mermaid diagrams​

In #9305, we upgraded to Mermaid v10.4 and added support for async diagram rendering. Docusaurus is now able to render new types of diagrams.

Query-string data attributes​

In #9028, we made it possible to set custom HTML data attributes though docusaurus-data-x query-string parameters. This makes it easier to embed a Docusaurus iframe on another site, and lets you customize the appearance of the embedded version with CSS.

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

Other features​

Other new features worth mentioning:

• #9189: new blog feedOptions.limit option
• #9071: add normalized SEO front matter support for the pages plugin
• #9171: the client-redirects plugin now supports fully qualified urls and query-string/hash in destination url
• #9171: new ESLint rule no-html-links
• #8384: new ESLint rule prefer-docusaurus-heading

Read Docusaurus v3.0.0 release notes for an exhaustive list of changes.

结语​

This release comes with a few features, but more importantly upgrades many pieces of the Docusaurus infrastructure.

The MDX upgrade consumed a lot of our time this year, and we worked hard to make this important upgrade less difficult for all of you.

Now that we've caught up with our infrastructure, we'll be back delivering useful documentation features very soon, in upcoming minor versions.

We would like to thank you for using Docusaurus over the years. The documentation framework space is becoming more competitive lately, and we will do our best to ensure that Docusaurus remains a competitive solution that stands out for its great flexibility.

Docusaurus v3 is now in beta and the official release is around the corner. This is the perfect time to start preparing your site for this new major version.

Docusaurus v3 comes with a few breaking changes, many of which can be handled today under Docusaurus v2. Preparing your site ahead of time can be done incrementally, and will make it easier to upgrade to v3.

主要的突破变化是从 MDX v1 升级到 MDX v3 。 请阅读 MDX v2 和 MDX v3 的版本说明获取更详细的信息。 MDX will now compile your Markdown content more strictly and with subtle differences.

This article will mostly focus on how to prepare your content for this new MDX version, and will also list a few other breaking changes that you can handle today.

Preparatory work​

Before preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest Docusaurus v2 version.

Depending on the complexity of your site, it may be a good idea to adopt the visual regression testing workflow that we recently presented. It could help you catch unexpected visual side effects occurring during the Docusaurus v3 upgrade.

We also recommend using the .mdx extension whenever you use JSX, import, or export (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.). In future versions of Docusaurus, .md files will be parsed as standard CommonMark, which does not support these features. In Docusaurus v3, .md files keep being compiled as MDX files, but it will be possible to opt-in for CommonMark.

为MDX v3做准备​

MDX is a major dependency of Docusaurus responsible for compiling your .md and .mdx files to React components.

MDX v3更加强大，但也带来了一些变化，可能需要您对内容进行一些重构。 MDX v3更加严格，一些在v1下编译良好的组件现在可能在v3下无法编译，最有可能的原因是{和<字符。

Upgrading MDX comes with all the breaking changes documented on the MDX v2 and MDX v3 release blog posts. 大多数重大变更来自MDX v2。 The MDX v2 migration guide has a section on how to update MDX files that will be particularly relevant to us. Also make sure to read the Troubleshooting MDX page that can help you interpret common MDX error messages.

还请确保阅读我们更新的 MDX 和 React 文档页面。

Using the MDX playground​

The MDX playground is your new best friend. It permits to understand how your content is compiled to React components, and troubleshoot compilation or rendering issues in isolation.

Each MDX version comes with its own playground:

• MDX 游乐场 - 当前版本
• MDX 游乐场 - v1

一起使用这两个MDX Playground，您很快就会注意到一些内容的编译不同或未能编译到 v3。

Using the MDX checker CLI​

We provide a docusaurus-mdx-checker CLI that permits to easily spot problematic content. 您可以在您的 Docusaurus v2 网站上运行这个命令来获取一个 MDX v3 下无法编译的文件列表。

npx docusaurus-mdx-checker

For each compilation issue, the CLI will log the file path and a line number to look at.

Common MDX problems​

我们将一些Docusaurus网站升级到 Docusaurus v3 和 MDX v3：

• Docusaurus PR
• React-Native PR
• Jest PR

These upgrades permitted us to aggregate the most common content problems, and document how to best handle them.

Bad usage of {​

The { character is used for opening JavaScript expressions. MDX will now fail if what you put inside {expression} is not a valid expression.

The object shape looks like {username: string, age: number}

Bad usage of <​

The < character is used for opening JSX tags. MDX will now fail if it thinks your JSX is invalid.

Use Android version <5

You can use a generic type like Array<T>

Follow the template "Road to <YOUR_MINOR_VERSION>"

Bad usage of GFM Autolink​

Docusaurus supports GitHub Flavored Markdown (GFM), but autolink using the <link> syntax is not supported anymore by MDX.

<sebastien@thisweekinreact.com>

<http://localhost:3000>

sebastien@thisweekinreact.com
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)

http://localhost:3000
[http://localhost:3000](http://localhost:3000)

小写 MDXComponent 映射​

对于提供自定义 MDXComponentmapping 的用户，组件现在是 "sandboxed"：

• h1 的映射 MDXComponent 仅用于# hi ，而不是用于<h1>hi</h1>
• 小写 自定义元素名称将不再被相应的 MDXComponent 组件所替代。

 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => <p {...props} className="my-paragraph"/>
-  myElement: (props) => <div {...props} className="my-class" />,
+  MyElement: (props) => <div {...props} className="my-class" />,
 };

Unintended extra paragraphs​

In MDX, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected <p> tags.

<div>Some **Markdown** content</div>
<div>
  Some **Markdown** content
</div>

<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>

<div>Some <strong>Markdown</strong> content</div>
<div><p>Some <strong>Markdown</strong> content</p></div>

 <figure>
   <img src="/img/myImage.png" alt="My alt" />
-  <figcaption>
-    My image caption
-  </figcaption>
+  <figcaption>My image caption</figcaption>
 </figure>

Unintended usage of directives​

Docusaurus v3 now uses Markdown Directives (implemented with remark-directive) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.

This is a :textDirective

::leafDirective

:::containerDirective

Container directive content

:::

The AWS re:Invent conf is great

The AWS re
conf is great

Unsupported indented code blocks​

MDX does not transform indented text as code blocks anymore.

    console.log("hello");

```js
console.log('hello');
```

MDX plugins​

All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now ES Modules only and do not support CommonJS anymore.

In practice this means that you can't do require("remark-plugin") anymore.

import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* site config using remark plugins here */
};

module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // site config...
  };
};

Other breaking changes​

Apart from MDX, there are other breaking changes that you can already prepare your site for, notably major version upgrades of important dependencies.

Node.js 18.0​

Node.js 16 reached End-of-Life, and Docusaurus v3 now requires Node.js >= 18.0.

React 18.0​

Docusaurus v3 now requires React >= 18.0.

React 18 comes with its own breaking changes that should be relatively easy to handle, depending on the amount of custom React code you created for your site.

Simple Docusaurus sites that only use our official theme code without swizzling do not have anything to do.

TypeScript 5.0​

Docusaurus v3 now requires TypeScript >= 5.0.

TypeScript base config​

The official Docusaurus TypeScript config has been re-internalized from the external package @tsconfig/docusaurus to our new monorepo package @docusaurus/tsconfig.

This new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades.

 {
   "devDependencies": {
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "^3.0.0-beta.0",
   }
 }

 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

Admonition warning​

For historical reasons, we support an undocumented admonition :::warning that renders with a red color.

However, the color and icon is historically wrong. Docusaurus v3 re-introduces :::warning admonition officially, documents it, and fix the color and icon.

Versioned sidebars​

This breaking change will only affect Docusaurus v2 early adopters who versioned their docs before v2.0.0-beta.10 (December 2021).

When creating version v1.0.0, the sidebar file contained a prefix version-v1.0.0/ that Docusaurus v3 does not support anymore.

{
  "version-v1.0.0/docs": [
    "version-v1.0.0/introduction",
    "version-v1.0.0/prerequisites"
  ]
}

{
  "docs": ["introduction", "prerequisites"]
}

Try Docusaurus v3 today​

Docusaurus v3 is now in beta, and already used in production by React-Native, Jest, and our own website.

We think this new Docusaurus version is robust and ready to be deployed in production. It should be released officially soon, after receiving a positive feedback from early adopters of our community.

We would really appreciate it if you try upgrading and report issues on the 3.0.0-beta.0 release discussion thread.

For most sites, the upgrade should be easy. If you prepared your site ahead of time as documented here, upgrading the following dependencies should be enough:

 {
   "dependencies": {
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/preset-classic": "3.0.0-beta.0",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0"
   }
 }

Ask for help​

We will be there to help you upgrade through the following support channels:

• Docusaurus v3 - Upgrade Support
• Docusaurus v3 - Discord channel #migration-v2-to-v3
• MDX v3 - 升级支持
• MDX v3 - Remark/Rehype 插件支持
• MDX v3 - Discord 频道 #migration-mdx-v3

Alternatively, you can look for a paid Docusaurus Service Provider to execute this upgrade for you. If your site is open source, you can also ask our community for free, benevolent help.

结语​

Docusaurus v3 is ready to try, and will be released soon. This article already gives you a good idea of all the major changes required to upgrade.

The initial 3.0 release is focusing on dependency and infrastructure upgrades that will permit us to implement new exciting features. It also comes with a few useful features that we will detail in the final release notes.

Upgrading Docusaurus is a good example: without reviewing all the pages one by one, it's hard to be sure there's no visual regression. Docusaurus v3 is around the corner (currently in beta), and we would like to help you do this upgrade with confidence.

This article introduces a visual regression testing workflow based on GitHub Actions, Playwright, and Argos. It is not directly coupled to Docusaurus or React, and can be adapted to work with other frontend applications and frameworks.

This workflow has been tested while upgrading Docusaurus v2 to v3, and already helped catch a few visual regressions on sites such as React Native, Jest, and the Docusaurus site itself.

Docusaurus v3 comes with infrastructure changes and major dependency upgrades such as MDX v3 and React 18, which can produce unexpected side effects. It would have been difficult to notice all the visual regressions without such a workflow. That's why we encourage site owners to consider adopting visual regression testing, especially for highly customized sites.

Workflow overview​

The general idea is pretty simple:

• Build your site in CI with GitHub Actions
• Take screenshots of all sitemap.xml pages with Playwright
• Upload them to Argos
• Do this for both Git branches main and pr-branch
• Compare the screenshots side-by-side in Argos

Argos will then report visual differences found between main and pr-branch as a GitHub commit status and pull-request comment. This can help you detect visual regressions ahead of time in an automated way.

Argos creates a report referencing all the visual differences found while comparing the 2 Git branches sites side-by-side, and provides a convenient UX to easily spot the difference.

Check the Docusaurus Argos page to explore our own website reports.

Here is a more concrete example of Argos reporting a visual regression found while upgrading the React-Native website:

Workflow implementation​

This section will describe the implementation details of each step of the workflow.

You will need to sign up to Argos and connect Argos to your GitHub repository

Dependencies​

This workflow requires the following dev dependencies, in addition to the usual Docusaurus ones:

yarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio

GitHub Action​

The GitHub action is responsible for executing the workflow for each Git branch.

A minimal workflow could look like:

name: Argos CI Screenshots

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  take-screenshots:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: current

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Install Playwright browsers
        run: yarn playwright install --with-deps chromium

      - name: Build the website
        run: yarn docusaurus build

      - name: Take screenshots with Playwright
        run: yarn playwright test

      - name: Upload screenshots to Argos
        run: yarn argos upload ./screenshots

Playwright config​

Playwright is responsible for taking screenshots of the website previously built locally by the GitHub action.

A minimal Playwright config could look like:

import {devices} from '@playwright/test';
import type {PlaywrightTestConfig} from '@playwright/test';

const config: PlaywrightTestConfig = {
  webServer: {
    port: 3000,
    command: 'yarn docusaurus serve',
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
      },
    },
  ],
};

export default config;

Playwright test​

A Playwright config is not enough: we also need to write a Playwright test file to generate the site screenshots.

import * as fs from 'fs';
import {test} from '@playwright/test';
import {argosScreenshot} from '@argos-ci/playwright';
import {extractSitemapPathnames, pathnameToArgosName} from './utils';

// Constants
const siteUrl = 'http://localhost:3000';
const sitemapPath = './build/sitemap.xml';
const stylesheetPath = './screenshot.css';
const stylesheet = fs.readFileSync(stylesheetPath).toString();

// Wait for hydration, requires Docusaurus v2.4.3+
// Docusaurus adds a <html data-has-hydrated="true"> once hydrated
// See https://github.com/facebook/docusaurus/pull/9256
function waitForDocusaurusHydration() {
  return document.documentElement.dataset.hasHydrated === 'true';
}

function screenshotPathname(pathname: string) {
  test(`pathname ${pathname}`, async ({page}) => {
    const url = siteUrl + pathname;
    await page.goto(url);
    await page.waitForFunction(waitForDocusaurusHydration);
    await page.addStyleTag({content: stylesheet});
    await argosScreenshot(page, pathnameToArgosName(pathname));
  });
}

test.describe('Docusaurus site screenshots', () => {
  const pathnames = extractSitemapPathnames(sitemapPath);
  console.log('Pathnames to screenshot:', pathnames);
  pathnames.forEach(screenshotPathname);
});

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Extract a list of pathnames, given a fs path to a sitemap.xml file
// Docusaurus generates a build/sitemap.xml file for you!
export function extractSitemapPathnames(sitemapPath: string): string[] {
  const sitemap = fs.readFileSync(sitemapPath).toString();
  const $ = cheerio.load(sitemap, {xmlMode: true});
  const urls: string[] = [];
  $('loc').each(function handleLoc() {
    urls.push($(this).text());
  });
  return urls.map((url) => new URL(url).pathname);
}

// Converts a pathname to a decent screenshot name
export function pathnameToArgosName(pathname: string): string {
  return pathname.replace(/^\/|\/$/g, '') || 'index';
}