为 Docusaurus v3 准备你的网站

2023 年 9 月 29 日 ·阅读时长 14 分钟

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 checker 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) 的结束标记 - 结束标记不匹配 mdast-util-mdx-jsx

预期在 paragraph 结束之前出现 <YOUR_MINOR_VERSION> (134:19-134:39) 的结束标记

如何准备

修复此错误的可用选项

使用内联代码：Array<T>
使用 HTML 代码：< 或 <
转义它：\< (不幸的是，\ 将在 MDX v1 下显示)

错误使用 GFM 自动链接

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

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>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 内联”（**、*、_、[link](/path)），您可能无法提前重构它，并且将不得不与 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 重新内部化为我们新的单一仓库包 @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（红色）。

版本化侧边栏

此重大更改只会影响 **Docusaurus v2 早期采用者**，他们在 v2.0.0-beta.10（2021 年 12 月）之前对文档进行版本控制。

在创建版本 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 现在处于 beta 版，并且已被 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

寻求帮助

结论