准备您的网站以适应 Docusaurus v3

2023年9月29日 · 阅读需 21 分钟

Sébastien Lorber

Docusaurus maintainer, This Week In React editor

注意

这篇博文是在 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、格式化程序、代码分析器等）的兼容性。在未来的 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

MDX playground 选项面板的屏幕截图，仅选中“使用 MDX”、“使用 remark-gfm”和“使用 remark-directive”选项

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

使您的内容面向未来

目标是重构有问题的內容，使其 能够与两个版本的 MDX 都良好地工作 。这样，当您升级到 Docusaurus v3 时，此内容将能够立即运行。

使用 MDX checker CLI

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

npx docusaurus-mdx-checker

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

终端屏幕截图，显示 MDX 检查器 CLI 输出示例，其中包含一些错误消息

提示

使用此 CLI 来估算使您的内容与 MDX v3 兼容需要多少工作量。

注意

此 CLI 尽力而为，只会报告编译错误。

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

常见的 MDX 问题

我们已经将一些 Docusaurus 站点升级到 Docusaurus v3 和 MDX v3：

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

错误使用 `{`

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

example.md

对象的形状看起来像 {username: string, age: number}

错误信息

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

如何准备

修复此错误的可用选项：

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

错误使用 `<`

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

example.md
使用 Android 版本 <5

您可以使用像 Array<T> 这样的泛型类型

遵循模板“通往 <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]>

<http://localhost:3000>

错误信息

名称中出现意外字符 @ (U+0040)，预期的是名称字符，例如字母、数字、$ 或 _；属性之前的空格；或者标签的结尾（注意：要在 MDX 中创建链接，请使用 [text](url)）

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

如何准备

使用常规 Markdown 链接，或删除 < 和 >。MDX 和 GFM 已经能够自动链接文本了。

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

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

小写 MDXComponent 映射

对于提供自定义 MDXComponent 映射的用户，组件现在是“沙箱化”的：

h1 的 MDXComponent 映射仅用于 # hi，而不用于 <h1>hi</h1>
小写的自定义元素名称将不再被其相应的 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>一些 **Markdown** 内容</div>
<div>
  一些 **Markdown** 内容
</div>

MDX v1 输出
<div>一些 **Markdown** 内容</div>
<div>一些 **Markdown** 内容</div>

MDX v3 输出
<div>一些 <strong>Markdown</strong> 内容</div>
<div><p>一些 <strong>Markdown</strong> 内容</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 内联”（**、*、_、[link](/path)），您可能无法提前重构它，并且必须在 Docusaurus v3 升级的同时进行。

无意中使用了指令

Docusaurus v3 现在使用 Markdown 指令（使用 remark-directive 实现）作为提供对警示和其他即将推出的 Docusaurus 功能支持的通用方法。

example.md
这是一个 :textDirective

::leafDirective

:::containerDirective

容器指令内容

:::

视觉变化

指令被解析的目的是由其他 Remark 插件处理。未处理的指令将被忽略，并且不会以其原始形式呈现回来。

example.md

AWS re:Invent 大会很棒

由于 :Invent 被解析为文本指令，因此现在将呈现为：

AWS re
大会很棒

如何准备

使用 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 重构到我们新的单体仓库包 @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 checker CLI​

常见的 MDX 问题​

错误使用 {​

错误使用 <​

错误使用 GFM 自动链接​

小写 MDXComponent 映射​

无意的额外段落​

无意中使用了指令​

不支持的缩进代码块​

MDX 插件​

其他重大更改​

Node.js 18.0​

React 18.0​

TypeScript 5.0​

TypeScript 基本配置​

警示警告​

版本化侧边栏​

今天尝试 Docusaurus v3​

寻求帮助​

总结​

预备工作

为 MDX v3 准备内容

使用 MDX playground

使用 MDX checker CLI

常见的 MDX 问题

错误使用 `{`

错误使用 `<`

错误使用 GFM 自动链接

小写 MDXComponent 映射

无意的额外段落

无意中使用了指令

不支持的缩进代码块

MDX 插件

其他重大更改

Node.js 18.0

React 18.0

TypeScript 5.0

TypeScript 基本配置

警示警告

版本化侧边栏

今天尝试 Docusaurus v3

寻求帮助

总结