升级到道格龙（Docusaurus）v3

本文档将帮助您将站点从道格龙（Docusaurus）v2 升级到道格龙（Docusaurus）v3。

道格龙（Docusaurus）v3 是一个新的主版本，包含破坏性变更，需要您相应地调整站点。我们将在此过程中为您提供指导，并提及一些可选的建议。

这不是完全重写，破坏性变更相对容易处理。最简单的站点最终只需更新 npm 依赖项即可升级。

主要的破坏性变更是从 MDX v1 升级到 MDX v3。阅读 MDX v2 和 MDX v3 发布说明了解详情。MDX 现在将更严格地编译您的 Markdown 内容，并存在细微差异。

升级前准备

升级前，我们建议为道格龙（Docusaurus）v3 准备您的站点。有一些变更您已经可以在道格龙（Docusaurus）v2 下逐步处理。这样做将有助于减少最终升级到道格龙（Docusaurus）v3 所需的工作量。

对于复杂的站点，我们还建议设置视觉回归测试，这是确保站点视觉一致性的好方法。道格龙（Docusaurus）v3 主要升级依赖项，预计不会产生任何视觉变化。

备注

查看 道格龙（Docusaurus）v3.0.0 的发布说明，并浏览拉取请求以获取额外有用信息和此处提到的每个变更背后的动机。

升级依赖项

升级到道格龙（Docusaurus）v3 需要升级核心道格龙（Docusaurus）依赖项（@docusaurus/name），还需要升级其他相关包。

道格龙（Docusaurus）v3 现在使用以下依赖项：

Node.js v18.0+
React v18.0+
MDX v3.0+
TypeScript v5.1+
prism-react-renderer v2.0+
react-live v4.0+
remark-emoji v4.0+
mermaid v10.4+

升级社区插件

如果您的站点使用第三方社区插件和主题，您可能需要升级它们。

在尝试升级之前，请确保这些插件与道格龙（Docusaurus）v3 兼容。

典型的 package.json 依赖项升级示例：

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

对于 TypeScript 用户：

package.json
 {
   "devDependencies": {
     // swap the external TypeScript config package for the new official one
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
     // upgrade React types to v18.0+
-    "@types/react": "^17.0.69",
+    "@types/react": "^18.2.29",
     // upgrade TypeScript to v5.1+
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

升级 MDX

MDX 是道格龙（Docusaurus）的主要依赖项，负责将您的 .md 和 .mdx 文件编译为 React 组件。

从 MDX v1 到 MDX v3 的过渡是采用道格龙（Docusaurus）v3 的主要挑战。大部分破坏性变更来自 MDX v2，而 MDX v3 是一个相对较小的发布。

在道格龙（Docusaurus）v2 下成功编译的某些文档现在可能在道格龙（Docusaurus）v3 下编译失败。

提前发现问题内容

在您的站点上运行 npx docusaurus-mdx-checker 以获取现在在道格龙（Docusaurus）v3 下将编译失败的文件列表。

此命令也是估算使您的内容兼容所需工作量的好方法。请记住，大部分工作可以通过为道格龙（Docusaurus）v3 准备内容来提前执行。

其他文档也可能渲染不同。

使用视觉回归测试

对于手动审查所有页面很复杂的大型站点，我们建议您设置视觉回归测试。

升级 MDX 伴随着 MDX v2 和 MDX v3 发布博客文章中记录的所有破坏性变更。大部分破坏性变更来自 MDX v2，而 MDX v3 是一个相对较小的发布。MDX v2 迁移指南有一个关于如何更新 MDX 文件的部分，这对我们特别相关。还要确保阅读 MDX 故障排除页面，它可以帮助您解释常见的 MDX 错误消息。

还要确保阅读我们更新的 MDX 和 React 文档页面。

使用 MDX 游乐场

MDX 游乐场是您的新好朋友。它允许您了解您的内容如何编译为 React 组件，并独立地故障排除编译或渲染问题。

为道格龙（Docusaurus）配置 MDX 游乐场选项

要在 MDX 游乐场上获得与道格龙（Docusaurus）v2 使用的编译行为类似，请打开这些选项：

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

并排使用两个 MDX 游乐场，您很快就会注意到某些内容的编译方式不同或在 v2 中编译失败。

使您的内容面向未来

目标将是重构您的问题内容，使其与两个版本的 MDX 都能很好地工作。这样，当您升级到道格龙（Docusaurus）v3 时，此内容已经可以开箱即用。

使用 MDX 检查器 CLI

我们提供了一个 docusaurus-mdx-checker CLI，可以轻松发现问题内容。在您的站点上运行此命令以获取在 MDX v3 下将编译失败的文件列表。

npx docusaurus-mdx-checker

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

提示

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

注意

此 CLI 是尽力而为，将仅报告编译错误。

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

常见 MDX 问题

道格龙（Docusaurus）无法详尽记录 MDX 带来的所有更改。这是 MDX v2 和 MDX v3 迁移指南的责任。

但是，通过升级几个道格龙（Docusaurus）站点，我们注意到大部分问题归结为我们为您记录的少数几种情况。

`{` 的错误使用

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

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

错误消息

Could not parse expression with acorn: Unexpected content after expression

如何升级

修复此错误的可用选项：

使用内联代码：{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>"

错误消息

Unexpected character 5 (U+0035) before name, expected a character that can start a name, such as a letter, $, or _

Expected a closing tag for <T> (1:6-1:9) before the end of paragraph end-tag-mismatch mdast-util-mdx-jsx

Expected a closing tag for <YOUR_MINOR_VERSION> (134:19-134:39) before the end of paragraph

如何升级

修复此错误的可用选项：

使用内联代码：Array<T>
使用 HTML 代码：< 或 <
转义它：\<

GFM 自动链接的错误使用

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

example.md
<[email protected]>

<http://localhost:3000>

Error messages

Unexpected character @ (U+0040) in name, expected a name character such as letters, digits, $, or _; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use [text](url))

Unexpected character / (U+002F) before local name, expected a character that can start a name, such as a letter, $, or _ (note: to create a link in MDX, use [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 v3 中，现在可以更容易地在 JSX 和 Markdown 之间交错，而无需额外的换行。在多行上编写内容也可能产生新的预期 <p> 标签。

视觉差异

查看此内容在 MDX v1 和 v3 中的渲染方式有何不同。

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

MDX v1 output
<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>

MDX v3 output
<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 语法，也可以用 { 和 } 包装此类内容以避免额外的 <p> 标签。

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

指令的意外使用

道格龙（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 不再将缩进文本转换为代码块。

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

视觉变化

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

如何升级

使用常规代码块语法而不是缩进：

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

其他 Markdown 不兼容性

以空格或标点符号开始或结束的强调

新的 MDX 解析器现在严格遵循 CommonMark 规范。CommonMark 规范引入了关于空格和标点符号周围强调的规则，这些规则与不使用空格分隔单词的语言特别不兼容，自 v0.14 以来。

日语和中文受此影响最大，但也有一些其他语言可能受到影响（例如泰语和高棉语），例如当您尝试强调内联代码或链接时。使用空格分隔单词的语言受影响要小得多。

以下示例中的 **（除了 `**`）在道格龙（Docusaurus）2 中按预期解析，但在道格龙（Docusaurus）3 中不再如此。

example.md
**Do not end a range of emphasis with a space. **Or `**` will not work as intended.

<!-- Japanese -->
**「。」の後に文を続けると`**`が意図した動作をしません。**また、**[リンク](https://docusaurus.io/)**や**`コード`**のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

查看详细条件和如何升级

如果 * 或 ** 符合以下任一条件，它将不再作为强调标记的开始：

下一个字符是空格（例如 word* word）
前一个字符是标点字符，下一个字符是字母（不是空格或标点字符）（例如 文**（文））

相反，如果 * 或 ** 符合以下任一条件，它将不再作为强调标记的结束：

前一个字符是空格（例如 word *word）
下一个字符是标点字符，前一个字符是字母（例如 文。**文）

"标点字符"包括非 ASCII 字符、括号、引号和包括 % 和 @ 在内的一些符号。更严格地说，2 字母 Unicode 类别以 P 开头的字符在这里被视为标点字符。

如何升级

如果违规的强调标记旁边有空格，请将空格移出强调范围：

english.md
**Do not end a range of emphasis with a space.** Or `**` will not work.

如果违规的强调标记被标点字符和字母包围，您可以通过以下方式修复它而不修改内容：

如果是普通 Markdown，请将文档转换为 MDX。
用原始 HTML 标签（<em> 或 <strong>）替换违规的强调标记：

japanese.mdx
<strong>「。」の後に文を続けると`**`が意図した動作をしません。</strong>また、<strong>[リンク](https://docusaurus.io/)</strong>や<strong>`コード`</strong>のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

虽然不是理想的解决方案，但您也可以在不将文档转换为 MDX 的情况下执行以下任一操作：

将最外面的标点字符移出强调标记。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません**。また、[**リンク**](https://docusaurus.io/)や・・・

在违规的 * 或 ** 外面放一个空格。此解决方案不会强制您将文档转换为 MDX。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません。** また、**[リンク](https://docusaurus.io/)** や **`コード`** のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

一个非官方的 remark 插件 remark-cjk-friendly 可以在大多数情况下修复此问题，而无需修改用中文、日语和韩语编写的 Markdown 源代码。

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 */
};

If you want to keep using CommonJS modules, you can use dynamic imports as a workaround that enables you to import ES modules inside a CommonJS module. Fortunately, the Docusaurus config supports the usage of an async function to let you do so.

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

For plugin authors

If you created custom Remark or Rehype plugins, you may need to refactor those, or eventually rewrite them completely, due to how the new AST is structured. We have created a dedicated support discussion to help plugin authors upgrade their code.

格式化工具

Prettier 是最常见的格式化工具，仅支持传统的 MDX v1，截至道格龙（Docusaurus）v3.0.0 还不支持 v3。您可以在代码的不兼容部分之前添加 {/* prettier-ignore */} 以使其与 Prettier 一起工作。

{/* prettier-ignore */}
<SomeComponent>Some long text in the component</SomeComponent>

如果您厌倦了太多 {/* prettier-ignore */} 插入，您可以考虑通过在 .prettierignore 文件中添加以下内容来禁用 Prettier 的 MDX 格式化，直到它开始支持 MDX v3：

.prettierignore
*.mdx

其他破坏性变更

除了 MDX v3 升级，以下是道格龙（Docusaurus）v3 带来的破坏性变更的详尽列表。

Node.js v18.0

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

如何升级

在您的计算机上安装 Node.js 18.0+。

最终，配置您的持续集成、CDN 或主机以使用这个新的 Node.js 版本。

您还可以更新站点的 package.json 以防止使用较旧的不支持版本：

package.json
 {
   "engines": {
-     "node": ">=16.14"
+     "node": ">=18.0"
   }
 }

在升级到道格龙（Docusaurus）v3 之前，将您的道格龙（Docusaurus）v2 站点升级到 Node.js 18。

React v18.0+

道格龙（Docusaurus）v3 现在需要 React >= 18.0。

React 18 带来了自己的破坏性变更，这些变更应该相对容易处理，具体取决于您为站点创建的自定义 React 代码量。官方主题和插件与 React 18 兼容。

如何升级

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

我们特别建议查找：

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

React 18 功能的实验性支持

React 18 带来了新功能：

<Suspense>
React.lazy()
startTransition

它们的道格龙（Docusaurus）支持被认为是实验性的。我们可能必须在未来调整集成，导致不同的运行时行为。

Prism-React-Renderer v2.0+

道格龙（Docusaurus）v3 将 prism-react-renderer 升级到 v2.0+。此库用于代码块语法高亮。

如何升级

这是一个包含破坏性变更的新主库版本，我们无法保证严格的向后兼容性。prism-react-renderer v2 发布说明不是很详尽，但道格龙（Docusaurus）用户需要注意 3 个主要更改。

依赖项应该升级：

package.json
 {
   "dependencies": {
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
 }

在道格龙（Docusaurus）配置文件中导入主题的 API 已更新：

docusaurus.config.js
- const lightTheme = require('prism-react-renderer/themes/github');
- const darkTheme = require('prism-react-renderer/themes/dracula');
+ const {themes} = require('prism-react-renderer');
+ const lightTheme = themes.github;
+ const darkTheme = themes.dracula;

以前，react-prism-render v1 默认包含更多语言。从 v2.0+ 开始，默认包含的语言更少。您可能需要向道格龙（Docusaurus）配置添加额外语言：

docusaurus.config.js
const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ['bash', 'diff', 'json'],
    },
  },
};

React-Live v4.0+

对于 @docusaurus/theme-live-codeblock 包的用户，道格龙（Docusaurus）v3 将 react-live 升级到 v4.0+。

如何升级

理论上，您无需做任何事情，您现有的交互式代码块应该像以前一样继续工作。

但是，这是一个包含破坏性变更的新主库版本，我们无法保证严格的向后兼容性。如果出现问题，请阅读 v3 和 v4 变更日志。

remark-emoji v4.0+

道格龙（Docusaurus）v3 将 remark-emoji 升级到 v4.0+。此库用于支持 Markdown 中的 :emoji: 快捷方式。

如何升级

大多数道格龙（Docusaurus）用户无需做任何事情。表情符号短代码用户应该阅读变更日志并仔细检查他们的表情符号是否按预期渲染。

破坏性变更 将 node-emoji 从 v1 更新到 v2。此更改引入了对许多新表情符号的支持，并删除了在 GitHub 上不再有效的旧表情符号短代码。

Mermaid v10.4+

对于 @docusaurus/theme-mermaid 包的用户，道格龙（Docusaurus）v3 将 mermaid 升级到 v10.4+。

如何升级

理论上，您无需做任何事情，您现有的图表应该像以前一样继续工作。

但是，这是一个包含破坏性变更的新主库版本，我们无法保证严格的向后兼容性。如果出现问题，请阅读 v10 变更日志。

TypeScript v5.1+

道格龙（Docusaurus）v3 现在需要 TypeScript >= 5.1。

如何升级

将您的依赖项升级到使用 TypeScript 5+

package.json
 {
   "devDependencies": {
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

TypeScript 基础配置

官方道格龙（Docusaurus）TypeScript 配置已从外部包 @tsconfig/docusaurus 重新内部化到我们的新 monorepo 包 @docusaurus/tsconfig。

这个新包与所有其他道格龙（Docusaurus）核心包一起版本化，将用于确保 TypeScript 向后兼容性和主版本升级时的破坏性变更。

如何升级

将外部 TypeScript 配置包替换为新的官方包

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

在您的 tsconfig.json 文件中使用它：

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

新配置加载器

道格龙（Docusaurus）v3 将其内部配置加载库从 import-fresh 更改为 jiti。它负责加载 docusaurus.config.js 或 sidebars.js 等文件，以及道格龙（Docusaurus）插件。

如何升级

理论上，您无需做任何事情，您现有的配置文件应该像以前一样继续工作。

但是，这是一个主要的依赖项交换，可能会发生微妙的行为变化。

提示框警告

出于历史原因，我们支持一个未记录的提示框 :::warning，它以红色渲染。

Warning

这是道格龙（Docusaurus）v2 的 :::warning 提示框。

但是，颜色和图标一直是错误的。道格龙（Docusaurus）v3 正式重新引入 :::warning 提示框，记录它，并修复颜色和图标。

注意

这是道格龙（Docusaurus）v3 的 :::warning 提示框。

如何升级

如果您之前使用了未记录的 :::warning 提示框，请确保验证每次使用黄色现在是否是合适的颜色。如果您想保持红色，请改用 :::danger。

道格龙（Docusaurus）v3 还弃用了 :::caution 提示框。请将 :::caution（黄色）重构为 :::warning（黄色）或 :::danger（红色）。

如果您想保持标题"caution"，您可能想将其重构为 :::warning[caution]（黄色）。

版本化侧边栏

此破坏性变更只会影响在 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"
  ]
}

如何升级

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

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

博客源限制

@docusaurus/plugin-content-blog 现在默认将 RSS 源限制为最后 20 个条目。对于大型道格龙（Docusaurus）博客，这是一个更合理的默认值，可以避免 RSS 文件越来越大。

如何升级

如果您不喜欢这个新的默认行为，可以使用新的 limit: false 源选项恢复到以前的"无限源"行为：

docusaurus.config.js
const blogOptions = {
  feedOptions: {
    limit: false,
  },
};

文档主题重构

对于 swizzle 了文档相关主题组件（如 @theme/DocPage）的用户，这些组件已经进行了重大重构，使其更容易自定义。

从技术上讲，这不是破坏性变更，因为这些组件被标记为不安全的 swizzle，但是许多道格龙（Docusaurus）站点弹出了文档相关组件，并且会感兴趣地知道他们的自定义可能会破坏道格龙（Docusaurus）。

如何升级

删除所有 swizzle 的组件，重新 swizzle 它们，并在新更新的组件上重新应用您的自定义。

或者，您可以查看拉取请求说明以了解新的主题组件树结构，并最终尝试手动修补您的 swizzle 组件。

可选变更

一些变更不是强制性的，但了解它们对于充分利用道格龙（Docusaurus）v3 仍然有用。

自动 JSX 运行时

道格龙（Docusaurus）v3 现在使用 React 18 的"自动" JSX 运行时。

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

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

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

ESM 和 TypeScript 配置

道格龙（Docusaurus）v3 支持 ESM 和 TypeScript 配置文件，采用这些新选项可能是个好主意。

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

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',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;

使用 `.mdx` 扩展名

我们建议在 Markdown 文件中使用 JSX、import 或 export（即 MDX 功能）时使用 .mdx 扩展名。它在语义上更正确，并提高了与外部工具（IDE、格式化工具、linter 等）的兼容性。

在道格龙（Docusaurus）的未来版本中，.md 文件将被解析为标准 CommonMark，它不支持这些功能。在道格龙（Docusaurus）v3 中，.md 文件继续编译为 MDX 文件，但可以选择加入 CommonMark。

升级数学包

如果您使用道格龙（Docusaurus）渲染数学方程，您应该升级 MDX 插件。

确保为道格龙（Docusaurus）v3（使用 MDX v3）使用 remark-math 6 和 rehype-katex 7。我们无法保证其他版本会工作。

{
-  "remark-math": "^3.0.0",
+  "remark-math": "^6.0.0",
-  "rehype-katex": "^5.0.0"
+  "rehype-katex": "^7.0.0"
}

hast-util-is-element 在道格龙（Docusaurus）v3 中现在是不必要的。如果您已安装它且不在其他地方使用它，可以通过运行 npm uninstall hast-util-is-element 来删除它。

关闭 MDX v1 兼容性

道格龙（Docusaurus）v3 带有 MDX v1 兼容性选项，默认开启。

docusaurus.config.js
export default {
  markdown: {
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

`comments` 选项

此选项允许在 MDX 中使用 HTML 注释，而 HTML 注释官方不再支持。

对于 MDX 文件，我们建议逐步使用 MDX {/* comments */} 而不是 HTML ，然后关闭此兼容性选项。

博客截断标记

默认博客截断标记现在支持  和 {/* truncate */}。

`admonitions` 选项

此选项允许使用道格龙（Docusaurus）v2 提示框标题语法：

:::note[Your Title]

content

:::

道格龙（Docusaurus）现在使用 Markdown 指令（通过 remark-directive 实现）实现提示框，提供指令标签的语法需要方括号：

:::note[Your Title]

content

:::

我们建议逐步使用新的 Markdown 指令标签语法，然后关闭此兼容性选项。

`headingIds` 选项

此选项允许使用道格龙（Docusaurus）v2 显式标题 id语法：

### Hello World {#my-explicit-id}

此语法现在在 MDX 中无效，需要转义 { 字符：\{#my-explicit-id}。

我们建议暂时保持此兼容性选项开启，直到我们提供与更新版本的 MDX 兼容的新语法。

故障排除

如果遇到任何升级问题，首先要尝试的是：

确保所有文档在 MDX 游乐场中编译，或使用 npx docusaurus-mdx-checker
删除 node_modules 和 package-lock.json，然后重新运行 npm install
运行 docusaurus clear 清除缓存
移除可能不支持道格龙（Docusaurus）v3 的第三方插件
删除所有 swizzle 的组件

尝试这些后，您可以通过以下支持渠道寻求帮助：

请考虑我们的时间很宝贵。为了确保您的支持请求不被忽略，我们恳请您：

提供一个我们可以轻松运行的最小复现，理想情况下使用 docusaurus.new 创建
提供一个显示问题实际运行的实时部署 URL（如果您的站点可以构建）
清楚地解释问题，比模糊的"它不工作"要详细得多
包含尽可能多的相关材料：代码片段、仓库 URL、git 分支 URL、完整堆栈跟踪、截图和视频
清晰、简洁地提出您的请求，向我们展示您已经努力帮助我们帮助您

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

升级依赖项​

升级 MDX​

使用 MDX 游乐场​

使用 MDX 检查器 CLI​

常见 MDX 问题​

{ 的错误使用​

< 的错误使用​

GFM 自动链接的错误使用​

小写 MDXComponent 映射​

意外的额外段落​

指令的意外使用​

不支持的缩进代码块​

其他 Markdown 不兼容性​

以空格或标点符号开始或结束的强调​

MDX 插件​

格式化工具​

其他破坏性变更​

Node.js v18.0​

React v18.0+​

Prism-React-Renderer v2.0+​

React-Live v4.0+​

remark-emoji v4.0+​

Mermaid v10.4+​

TypeScript v5.1+​

TypeScript 基础配置​

新配置加载器​

提示框警告​

版本化侧边栏​

博客源限制​

文档主题重构​

可选变更​

自动 JSX 运行时​

ESM 和 TypeScript 配置​

使用 .mdx 扩展名​

升级数学包​

关闭 MDX v1 兼容性​

comments 选项​

admonitions 选项​

headingIds 选项​

故障排除​

升级依赖项

升级 MDX

使用 MDX 游乐场

使用 MDX 检查器 CLI

常见 MDX 问题

`{` 的错误使用

`<` 的错误使用

GFM 自动链接的错误使用

小写 MDXComponent 映射

意外的额外段落

指令的意外使用

不支持的缩进代码块

其他 Markdown 不兼容性

以空格或标点符号开始或结束的强调

MDX 插件

格式化工具

其他破坏性变更

Node.js v18.0

React v18.0+

Prism-React-Renderer v2.0+

React-Live v4.0+

remark-emoji v4.0+

Mermaid v10.4+

TypeScript v5.1+

TypeScript 基础配置

新配置加载器

提示框警告

版本化侧边栏

博客源限制

文档主题重构

可选变更

自动 JSX 运行时

ESM 和 TypeScript 配置

使用 `.mdx` 扩展名

升级数学包

关闭 MDX v1 兼容性

`comments` 选项

`admonitions` 选项

`headingIds` 选项

故障排除