宣布 Docusaurus 3.0

2023年10月31日 · 阅读需 16 分钟

Docusaurus maintainer, This Week In React editor

今天，我们很高兴 宣布 Docusaurus 3.0 ！🥳

在 Meta 开源项目 , 我们相信 Docusaurus 将帮助您以 最小的努力 构建 最佳的文档网站 ，让您可以 专注于真正重要的事情 : 编写内容。

这是 Docusaurus 的一个新的 主要版本 ，它带来了 令人兴奋的新功能 和升级的依赖项。

根据 语义版本控制 原则，此版本包含我们在 v3 升级指南 中详尽记录的 重大更改 。重大更改可能会令人烦恼，但它们对于为我们计划实施的 新一波 Docusaurus 功能 奠定基础是必要的。

我们最初计划发布更频繁的主要版本，但 Docusaurus v3 的发布时间比预期要长。在我们积累的重大更改中， 升级到 MDX v3 可能是采用此新版本的主要挑战。我们加倍努力，使此升级尽可能轻松，尤其是在添加了 MDX v1 的兼容性选项方面。

最简单的网站只需要升级几个 npm 依赖项。对于更复杂的网站，我们提出了一些策略，可以帮助您更自信地进行升级：

提前准备您的网站，逐步进行，同时保留在 Docusaurus v2 上
设置视觉回归测试以捕获升级过程中发生的意外视觉更改

关于 Docusaurus v2

根据我们的发布流程，Docusaurus v2 现在已进入 维护模式 。它将仅在 3 个月内（直到 2024 年 1 月 31 日）接收主要安全问题的支持。建议在此时间范围内升级到 v3。

重大更改

本节仅为您提供快速浏览。所有重大更改都在 v3 升级指南 中进行了详尽的记录。

Docusaurus v3 将一些依赖项升级到新的主要版本，每个版本都包含其自身的重大更改：

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

典型的 package.json 依赖项升级如下所示：

package.json
 {
   "dependencies": {
     // 升级到 Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // 升级到 MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // 升级到 prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // 升级到 React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // 将 Docusaurus 开发依赖项升级到 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": {
     // 需要 Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

除了 MDX v3 之外，这些升级的依赖项带来的大多数重大更改都已在内部为您处理：大多数情况下，您无需执行任何操作。在依赖项之外，显式来自 Docusaurus 代码库的唯一功能性重大更改是：

#9189 ：新的默认博客 RSS 提要限制为 20 个条目
#9308 ：修复并重新引入 :::warning 警告，弃用 :::caution
#9310 ：删除旧版本的侧边栏 ID 前缀，用于在 v2.0.0-beta.10（2021 年 12 月）之前进行版本控制的网站
#7966 ：重构文档主题组件，最终需要您重新调整它们

亮点

以下是此新版本中一些有用的新功能的非详尽列表。所有功能都在 Docusaurus v3.0.0 发行说明 中列出。

Markdown

Docusaurus v3 从 MDX v1 升级到 MDX v3：

在 #8288 中，我们升级到 MDX v2 （迁移指南）
在 #9451 中，我们升级到 MDX v3 （迁移指南）

这个新的 MDX 版本 对于内容编写者和插件作者来说要好得多 ，并为实现令人兴奋的新 Markdown 功能奠定了基础。

MDX v3 - 主要挑战

从 MDX v1 到 MDX v3 的过渡是 采用 Docusaurus v3 的主要挑战 。

在 Docusaurus v2 下成功编译的一些文档现在可能 无法在 Docusaurus v3 下编译 ，而另一些文档的 渲染方式可能不同 。

大多数重大更改来自 MDX v2 ，而 MDX v3 是一个相对较小的版本。 MDX v2 迁移指南包含一个关于如何更新 MDX 文件的部分，这与我们特别相关。还要确保阅读 MDX 疑难解答页面，该页面可以帮助您解释常见的 MDX 错误消息。

不要害怕 。大多数问题 很容易解决，并且通常与您现在需要转义的 { 和 < 字符有关。但是，根据您网站的大小，您可能需要编辑许多文件并感到不知所措。为此，我们提供了一个命令 npx docusaurus-mdx-checker 来帮助您估计要完成的工作量，我们建议您提前准备您的网站。

如果您创建了自定义 MDX 插件（Remark/Rehype），则 AST 略有不同，您可能需要重构它们。

这尤其使我们能够添加 CommonMark 模式，这应该使现有文档更容易采用 Docusaurus。它目前是可选的且 实验性的 ，并且有限制（某些 Docusaurus 功能将无法正常工作）。在 Docusaurus v3 中，所有文件仍然被解释为 MDX，但我们计划在即将发布的主要版本中将 .md 文件解释为 CommonMark，并建议对使用 JSX 或 ES 模块的任何文件使用 .mdx 扩展名。

我们还引入了一种新的方法来全局配置网站的 Markdown ，并计划稍后添加更多灵活的选项。

docusaurus.config.js
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 现在使用 remark-directive 插件来支持警告。这也为您提供了创建您自己的 Remark 插件以使用您自己的自定义指令（例如 :textDirective、::leafDirective 或 :::containerDirective）扩展 Markdown 的能力。

ESM 和 TypeScript 配置

在 #9317 中，我们添加了对 ES 模块和 TypeScript 配置文件的支持，包括站点配置、文档侧边栏、插件和预设。

以下是有两个 TypeScript 示例，为您提供具有 IDE 自动完成功能的现代体验：

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

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',
  // 您的站点配置 ...
  presets: [
    [
      'classic',
      {
        // 您的预设配置 ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // 您的主题配置 ...
  } satisfies Preset.ThemeConfig,
};

export default config;

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

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

export default sidebars;

未列出的内容

Docusaurus 已经在我们的 3 个内容插件（文档、博客、页面）中支持了 draft: true 前端选项，这允许您从生产版本中删除一些页面。

在 #8004 中，我们引入了一个新的 unlisted: true 前端选项，它将使您的页面在生产版本中可用，同时“隐藏”它们并使它们无法发现，除非您拥有 URL。这使得您可以轻松地请求在最终发布之前对内容进行反馈的工作流程。

未列出的内容将：

从 sitemap.xml 中排除
通过 <meta name="robots" content="noindex, nofollow" /> 从 SEO 结果中排除
从博客 RSS 提要中排除
从 Algolia DocSearch 结果中排除
从站点导航栏项目、文档侧边栏、博客侧边栏、博客存档、标签页面等中过滤掉

未列出的内容还将显示一个横幅，以便您在内容准备好黄金时段后不要忘记将其关闭。这是一个未列出的博客文章的示例：

/tests/blog/unlisted-post

React 18

在 #8961 中，我们升级到 React 18。这很重要，尤其是在逐步采用并发 React 功能方面，以及即将推出的令人兴奋的功能，例如构建时 React 服务器组件。

此新版本的 React 对于大多数 Docusaurus 网站来说应该是即插即用的替换。它包含我们在 Docusaurus 代码库中内部处理的重大更改。如果您的站点使用了大量的自定义 React 代码，我们建议您查看有关如何升级到 React 18 的官方文章，特别是新的自动批处理行为。

对 React 18 功能的实验性支持

React 18 带来了新功能：

<Suspense>
React.lazy()
startTransition()

它们在 Docusaurus 中的支持被认为是 实验性的 。我们将来可能需要调整集成，从而导致不同的运行时行为。

自动 JSX 运行时

Docusaurus 现在使用 “自动” JSX 运行时。

不再需要在不使用任何 React API 的 JSX 文件中导入 React。

src/components/MyComponent.js
- import React from 'react';

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

调试版本

现在可以在开发模式下构建静态站点。

docusaurus build --dev

调试与 React 相关的問題

Docusaurus 将更多错误记录到控制台，特别是通过新的 onRecoverableError 回调记录的 React 18 水合错误。

这种新的构建模式对于 解决 React 问题 特别有用。Docusaurus 将使用 React 的开发版本，从而生成详细且可读的错误消息，而不是指向 React 错误解码器页面的压缩错误消息。

TypeScript

Docusaurus v3 现在需要最低版本的 TypeScript 5.0。

我们将基本推荐的 TypeScript 配置重新整合到一个新的官方包中：

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

我们还为 Docusaurus 核心类型、插件和预设选项提供了更清晰、更规范的导出，您可以在全新的 TypeScript 配置文件中使用它们：

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

代码块

在 #9316 中，由于 prism-react-renderer v2 的升级，我们改进了语法高亮显示。例如，bash 参数 --save 现在已着色：

npm install --save some-package

交互式代码编辑器也升级到 react-live v4，它带有一个新的 sucrase 编译器。它更快、更轻量，并支持现代功能，特别是 TypeScript 类型注释。

实时编辑器

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

结果

在 #8982 和 #8870 中，我们还添加了对类似 TeX、类似 Haskell 和 WebAssembly 注释语法的魔术注释支持。

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

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

Mermaid 图表

在 #9305 中，我们升级到 Mermaid v10.4 并添加了对异步图表渲染的支持。Docusaurus 现在能够渲染新型图表。

思维导图

象限图

查询字符串数据属性

在 #9028 中，我们使通过 docusaurus-data-x 查询字符串参数设置自定义 HTML 数据属性成为可能。这使得在另一个站点上嵌入 Docusaurus iframe 变得更容易，并允许您使用 CSS 自定义嵌入版本的显示。

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

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

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

其他功能

其他值得一提的新功能：

#9189 ：新的博客 feedOptions.limit 选项
#9071 ：添加对页面插件的规范化 SEO 前端支持
#9171 ：客户端重定向插件现在支持完全限定的 url 和目标 url 中的查询字符串/哈希值
#9171 ：新的 ESLint 规则 no-html-links
#8384 ：新的 ESLint 规则 prefer-docusaurus-heading

阅读 Docusaurus v3.0.0 发行说明 以获取所有更改的详尽列表。

结论

此版本包含一些新功能，但更重要的是 升级了 Docusaurus 基础架构的许多部分 。

MDX 升级占据了我们今年的大量时间，我们努力让这个重要的升级对大家来说不那么困难。

现在我们已经赶上了我们的基础架构，我们将很快在即将发布的次要版本中 提供有用的文档功能 。

感谢您多年来使用 Docusaurus。文档框架领域最近竞争越来越激烈，我们将尽最大努力确保 Docusaurus 保持一个 具有竞争力的解决方案 ，并以其出色的 灵活性 而脱颖而出。

重大更改​

亮点​

Markdown​

ESM 和 TypeScript 配置​

未列出的内容​

React 18​

自动 JSX 运行时​

调试版本​

TypeScript​

代码块​

Mermaid 图表​

查询字符串数据属性​

其他功能​

结论​