为 Docusaurus v3 准备您的站点

2023年9月29日 ·阅读约16分钟

Sébastien Lorber

Docusaurus 维护者，《本周 React》编辑

警告

这篇博文撰写时 Docusaurus v3 仍处于测试阶段。如果您要升级到 Docusaurus v3 的当前稳定版本，请注意依赖项版本和升级步骤可能有所变化。请使用升级指南获取最新的迁移步骤。

Docusaurus v3 现已进入测试阶段，正式发布也即将到来。现在是开始为这个新主要版本准备您的网站的最佳时机。

Docusaurus v3 带来了一些重大变更，其中许多变更可以在 Docusaurus v2 下今天就开始处理。提前准备您的网站可以逐步进行，这将使升级到 v3 更加容易。

主要的重大变更时从 MDX v1 升级到 MDX v3。请阅读MDX v2 和MDX v3 的发布说明以获取详细信息。MDX 现在将更严格地编译您的 Markdown 内容，并会存在一些细微差异。

本文将主要关注如何为这个新的 MDX 版本准备您的内容，并列出一些您今天就可以处理的其他重大变更。

警告

本文提到了 Docusaurus v3 的大多数重大变更，但并非详尽无遗。请阅读v3.0.0-beta.0 发布说明以获取完整列表。

不用担心

这篇博文内容很多，但许多 Docusaurus v2 网站只需进行极少改动即可升级。

如果您的网站规模相对较小，且只有少量自定义内容，您可能可以立即升级到 Docusaurus v3。

准备工作

在准备 Docusaurus v3 升级之前，我们建议您升级到最新的Docusaurus v2 版本。

根据您网站的复杂程度，采用我们最近介绍的视觉回归测试工作流程可能是一个好主意。这可以帮助您捕获 Docusaurus v3 升级过程中出现的意外视觉副作用。

我们还建议您在 Markdown 文件中使用 JSX、import 或 export（即 MDX 功能）时，始终使用 .mdx 扩展名。这在语义上更正确，并能提高与外部工具（IDE、格式化工具、Linter 等）的兼容性。在 Docusaurus 的未来版本中，.md 文件将作为标准 CommonMark 进行解析，它不支持这些功能。在 Docusaurus v3 中，.md 文件仍会作为 MDX 文件编译，但未来将可以选择使用 CommonMark。

为 MDX v3 准备内容

MDX 是 Docusaurus 的一个主要依赖项，负责将您的 .md 和 .mdx 文件编译为 React 组件。

MDX v3 更好，但也带来了一些可能需要您稍作内容重构的变更。MDX v3 更严格，一些在 v1 下编译正常组件现在可能在 v3 下编译失败，最可能的原因是 { 和 < 字符。

升级 MDX 包含了 MDX v2 和 MDX v3 发布博文中记录的所有重大变更。大多数重大变更来自 MDX v2。 MDX v2 迁移指南中有一个关于如何更新 MDX 文件的部分，这与我们特别相关。此外，请务必阅读MDX 故障排除页面，它可以帮助您理解常见的 MDX 错误消息。

请务必阅读我们更新后的MDX 和 React 文档页面。

寻求帮助

我们有一个专门的MDX v3 - 升级支持讨论。

使用 MDX playground

MDX playground 将是您新的得力助手。它能帮助您理解内容如何编译为 React 组件，并独立排查编译或渲染问题。

每个 MDX 版本都带有其自己的 playground

为 Docusaurus 配置 MDX playground 选项

为了获得与 Docusaurus v2 相似的编译行为，请在MDX playground上开启以下选项

使用 MDX
使用 remark-gfm
使用 remark-directive

Screenshot of the MDX playground's options panel, with only the "Use MDX", "Use remark-gfm", and "Use remark-directive" options checked

并排使用这两个 MDX playground，您很快会注意到某些内容在 v3 中编译方式不同或无法编译。

让您的内容面向未来

目标是重构您的问题内容，使其在两个 MDX 版本下都能正常工作。这样，当您升级到 Docusaurus v3 时，这些内容将开箱即用。

使用 MDX 检查器 CLI

我们提供了一个 docusaurus-mdx-checker CLI，可以轻松发现有问题的内容。今天就在您的 Docusaurus v2 网站上运行此命令，以获取在 MDX v3 下无法编译的文件列表。

npx docusaurus-mdx-checker

对于每个编译问题，CLI 将记录文件路径和要查看的行号。

Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages

提示

使用此 CLI 估算所需工作量，以使您的内容与 MDX v3 兼容。

警告

此 CLI 尽最大努力，但仅报告编译错误。

它不会报告不会产生错误但可能影响内容显示方式的细微编译更改。为了发现这些问题，我们建议使用视觉回归测试。

常见 MDX 问题

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

这些升级使我们能够汇总最常见的内容问题，并记录如何最佳地处理它们。

`{` 的错误用法

{ 字符用于开启JavaScript 表达式。如果 {expression} 中放置的内容不是有效的表达式，MDX 将会失败。

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

错误信息

无法使用 acorn 解析表达式：表达式后出现意外内容

如何准备

修复此错误的可用选项

使用行内代码：{username: string, age: number}
使用 HTML 代码：{
转义它：\{

`<` 的错误用法

< 字符用于开启JSX 标签。如果 MDX 认为您的 JSX 无效，它将会失败。

example.md
Use Android version <5

You can use a generic type like Array<T>

Follow the template "Road to <YOUR_MINOR_VERSION>"

错误信息

名称前出现意外字符 5 (U+0035)，预期字符应能作为名称的开头，例如字母、$ 或 _

在 paragraph 结束标签之前，预期 <T> (1:6-1:9) 有一个关闭标签，end-tag-mismatch mdast-util-mdx-jsx

在 paragraph 结束之前，预期 <YOUR_MINOR_VERSION> (134:19-134:39) 有一个关闭标签

如何准备

修复此错误的可用选项

使用行内代码：Array<T>
使用 HTML 代码：< 或 <
转义它：\< （不幸的是，在 MDX v1 下 \ 会被显示）

GFM 自动链接的错误用法

Docusaurus 支持 GitHub Flavored Markdown (GFM)，但 MDX 不再支持使用 <link> 语法的自动链接。

example.md
<[email protected]>

<https://:3000>

错误信息

名称中出现意外字符 @ (U+0040)，预期字符应为名称字符，如字母、数字、$ 或 _；属性前的空白；或标签的结束（注意：在 MDX 中创建链接，请使用 [文本](url)）

本地名称前出现意外字符 / (U+002F)，预期字符应能作为名称的开头，例如字母、$ 或 _（注意：在 MDX 中创建链接，请使用 [文本](url)）

如何准备

使用常规 Markdown 链接，或者移除 < 和 >。MDX 和 GFM 已经能够自动链接字面量。

example.md
[email protected]
[[email protected]](mailto:[email protected])

https://:3000
[https://:3000](https://:3000)

小写 MDXComponent 映射

对于提供自定义 MDXComponent 映射的用户，组件现在被“沙盒化”了

h1 的 MDXComponent 映射只用于 # hi，而不用于 hi
**小写**的自定义元素名称将不再被其相应的 MDXComponent 组件替换

视觉差异

您的 MDXComponent 组件映射可能不会像以前那样应用，并且您的自定义组件可能不再被使用。

如何准备

对于原生 Markdown 元素，您可以继续使用**小写**：p、h1、img、a...

对于任何其他元素，**请使用大写名称**。

src/theme/MDXComponents.js
 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" />,
 };

意外的额外段落

在 MDX 中，现在可以更容易地交错使用 JSX 和 Markdown，而无需额外的换行符。在多行上编写内容也可能产生新的预期 <p> 标签。

视觉差异

查看 MDX v1 和 v3 如何不同地渲染此内容。

example.md
<div>Some **Markdown** content</div>
<div>
  Some **Markdown** content
</div>

MDX v1 输出
<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>

MDX v3 输出
<div>Some <strong>Markdown</strong> content</div>
<div><p>Some <strong>Markdown</strong> content</p></div>

如何准备

如果您不想要额外的 <p> 标签，请根据具体情况重构内容以使用单行 JSX 标签。

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

如果您的内容包含“Markdown 行内元素”（**、*、_、[链接](/路径)），您可能无法提前重构它，将需要与 Docusaurus v3 升级同时进行。

意外的指令用法

Docusaurus v3 现在使用Markdown 指令（通过 remark-directive 实现）作为一种通用方式来支持提示框以及其他即将推出的 Docusaurus 功能。

example.md
This is a :textDirective

::leafDirective

:::containerDirective

Container directive content

:::

视觉变化

指令的解析目的是由其他 Remark 插件处理。未处理的指令将被忽略，并且不会以其原始形式重新渲染。

example.md
The AWS re:Invent conf is great

由于 :Invent 被解析为文本指令，它现在将渲染为

The AWS re
conf is great

如何准备

使用 HTML 代码：:
在 : 后添加一个空格（如果合适）：: text
转义它：\: （不幸的是，在 MDX v1 下 \ 会被显示）

不支持的缩进代码块

MDX 不再将缩进文本转换为代码块。

example.md
    console.log("hello");

视觉变化

此次升级通常不会产生新的 MDX 编译错误，但可能导致内容以意想不到的方式渲染，因为不再存在代码块。

如何准备

使用常规代码块语法代替缩进

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

MDX 插件

MDX 生态系统中所有官方包（Unified、Remark、Rehype 等）现在仅支持 ES 模块，不再支持 CommonJS。

实际上，这意味着您不能再使用 require("remark-plugin")。

如何准备

Docusaurus v3 现在支持ES 模块配置文件。我们建议您将配置文件迁移到 ES 模块，这将使您能够轻松导入 Remark 插件

docusaurus.config.js
import remarkPlugin from 'remark-plugin';

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

如果您想继续使用 CommonJS 模块，您可以使用动态导入作为一种变通方法，在 CommonJS 模块中导入 ES 模块。幸运的是，Docusaurus 配置支持使用异步函数来实现此目的。

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

对于插件作者

如果您创建了自定义的 Remark 或 Rehype 插件，您可能需要重构它们，或者最终完全重写它们，因为新的 AST 结构发生了变化。我们创建了一个专门的支持讨论，以帮助插件作者升级他们的代码。

其他重大变更

除了 MDX 之外，还有其他您可以提前为您的网站准备的重大变更，特别是重要依赖项的主要版本升级。

Node.js 18.0

Node.js 16 已达到生命周期结束，Docusaurus v3 现在需要 Node.js >= 18.0。

如何准备

在升级到 Docusaurus v3 之前，将您的 Docusaurus v2 网站升级到 Node.js 18。

React 18.0

Docusaurus v3 现在需要 React >= 18.0。

React 18 带来了其自身的重大变更，根据您为网站创建的自定义 React 代码量，这些变更应该相对容易处理。

仅使用我们官方主题代码且未进行魔改的简单 Docusaurus 网站无需执行任何操作。

如何准备

阅读官方的 React v18.0 和如何升级到 React 18，并查看您自己的 React 代码，以确定哪些组件可能受此次 React 18 升级影响。

我们特别建议留意

有状态组件的自动批处理
控制台中报告的新的 React 水合错误

TypeScript 5.0

Docusaurus v3 现在需要 TypeScript >= 5.0。

如何准备

在升级到 Docusaurus v3 之前，将您的 Docusaurus v2 网站升级到 TypeScript 5。

TypeScript 基础配置

官方的 Docusaurus TypeScript 配置已从外部包 @tsconfig/docusaurus 迁移到我们新的 monorepo 包 @docusaurus/tsconfig。

这个新包与所有其他 Docusaurus 核心包一起进行版本控制，并将用于确保 TypeScript 向后兼容性以及主要版本升级时的重大变更。

如何准备

新的 Docusaurus v3 TypeScript 配置与之前的 Docusaurus v2 TypeScript 配置基本相同。如果您已升级到 TypeScript 5，那么在 v2 网站上使用 Docusaurus v3 配置已经是可行的

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

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

提示框警告

由于历史原因，我们支持一个未文档化的提示框 :::warning，它会以红色渲染。

警告

这是一个 Docusaurus v2 的 :::warning 提示框。

然而，其颜色和图标在历史上是错误的。Docusaurus v3 正式重新引入了 :::warning 提示框，对其进行了文档化，并修正了颜色和图标。

警告

这是一个 Docusaurus v3 的 :::warning 提示框。

如何准备

如果您之前使用了未文档化的 :::warning 提示框，请务必检查每处使用，确认黄色现在是否是合适的颜色。如果您想保留红色，请改用 :::danger。

Docusaurus v3 也废弃了 :::caution 提示框。请将 :::caution（黄色）重构为 :::warning（黄色）或 :::danger（红色）。

版本化侧边栏

此重大变更仅影响在 v2.0.0-beta.10（2021 年 12 月）之前对文档进行了版本化的 Docusaurus v2 早期采用者。

创建 v1.0.0 版本时，侧边栏文件包含前缀 version-v1.0.0/，Docusaurus v3 不再支持该前缀。

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

如何准备

您的 Docusaurus v2 网站能够类似地处理这两种侧边栏格式。

您可以从您的版本化侧边栏中移除无用的版本前缀。

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

立即试用 Docusaurus v3

Docusaurus v3 现已进入测试阶段，并已被 React-Native、Jest 和我们自己的网站在生产环境中使用。

我们认为这个新的 Docusaurus 版本稳定可靠，可以部署到生产环境。在收到社区早期采用者的积极反馈后，它应该会很快正式发布。

如果您尝试升级并在3.0.0-beta.0 发布讨论帖中报告问题，我们将不胜感激。

对于大多数网站，升级应该会很简单。如果您按照本文档的说明提前准备了您的网站，升级以下依赖项就足够了

package.json
 {
   "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"
   }
 }

寻求帮助

我们将通过以下支持渠道帮助您升级

或者，您可以寻找付费的 Docusaurus 服务提供商为您执行此升级。如果您的网站是开源的，您也可以向我们的社区寻求免费、善意的帮助。

结论

Docusaurus v3 已准备好试用，并即将发布。本文已经让您很好地了解了升级所需的所有主要变更。

最初的 3.0 版本专注于依赖项和基础设施升级，这将使我们能够实现令人兴奋的新功能。它还附带了一些有用的功能，我们将在最终的发布说明中详细说明。

准备工作​

为 MDX v3 准备内容​

使用 MDX playground​

使用 MDX 检查器 CLI​

常见 MDX 问题​

{ 的错误用法​

< 的错误用法​

GFM 自动链接的错误用法​

小写 MDXComponent 映射​

hi

意外的额外段落​

意外的指令用法​

不支持的缩进代码块​

MDX 插件​

其他重大变更​

Node.js 18.0​

React 18.0​

TypeScript 5.0​

TypeScript 基础配置​

提示框警告​

版本化侧边栏​

立即试用 Docusaurus v3​

寻求帮助​

结论​

准备工作

为 MDX v3 准备内容

使用 MDX playground

使用 MDX 检查器 CLI

常见 MDX 问题

`{` 的错误用法

`<` 的错误用法

GFM 自动链接的错误用法

小写 MDXComponent 映射

意外的额外段落

意外的指令用法

不支持的缩进代码块

MDX 插件

其他重大变更

Node.js 18.0

React 18.0

TypeScript 5.0

TypeScript 基础配置

提示框警告

版本化侧边栏

立即试用 Docusaurus v3

寻求帮助

结论