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

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

We are happy to announce Docusaurus 3.1.

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

Today, we are happy to announce Docusaurus 3.0! 🥳

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.

Frontend developers often need to upgrade npm dependencies, but those upgrades can feel scary and lead to subtle UI side effects not caught by your regular test suite.

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.