版本：3.5.2

升级到 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 游乐场选项

要获得类似于 Docusaurus v2 使用的编译行为，请在MDX 游乐场上启用以下选项

使用 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 游乐场，您很快就会注意到某些内容的编译方式不同或在 v2 中无法编译。

使您的内容面向未来

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

使用 MDX 检查器 CLI

我们提供了一个docusaurus-mdx-checker CLI，它允许轻松发现有问题的內容。在您的站点上运行此命令以获取将在 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 无法详尽地记录 MDX 带来的所有更改。这是MDX v2 和 MDX v3 迁移指南的职责。

然而，在升级了一些 Docusaurus 站点后，我们注意到大多数问题都归结为我们已为您记录的几个案例。

错误使用 `{`

{ 字符用于打开 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 代码：< 或 <
转义它：\<

错误使用 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 映射的用户，组件现在已“沙盒化”

MDXComponent 映射 h1 仅用于 # 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 输出
<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 语法，还可以使用 { 和 } 包裹此类内容以避免额外的 <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.org.cn/)**や**`コード`**のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

查看详细的条件和如何升级

如果 * 或 ** 满足以下任一条件，它将不再作为强调标记的开头。

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

相反，如果 * 或 ** 满足以下任一条件，它将不再作为强调标记的结尾。

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

“标点符号”包括非 ASCII 字符、括号、引号和一些符号，包括 % 和 @。更严格地说，此处将 Unicode 类别以 P 开头的 2 个字母的字符视为标点符号。

如何升级

如果错误的强调标记紧挨着空格，请将空格移出强调范围

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.org.cn/)</strong>や<strong>`コード`</strong>のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

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

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

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

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

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

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 结构，你可能需要重构这些插件，或者最终完全重写它们。我们创建了一个专门的支持讨论来帮助插件作者升级他们的代码。

格式化工具

Prettier，最常用的格式化工具，目前（截至 Docusaurus v3.0.0）仅支持旧版 MDX v1，不支持 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重新内部化到我们的新单一仓库包@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，它以红色渲染。

警告

这是一个 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"]
}

博客 Feed 限制

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

如何升级

如果您不喜欢这种新的默认行为，可以使用新的limit: false feed 选项恢复到以前的“无限 feed”行为。

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

文档主题重构

对于修改了文档相关主题组件（例如@theme/DocPage）的用户，这些组件已进行了重大重构，以方便自定义。

从技术上讲，这不是一个重大更改，因为这些组件被标记为不安全修改，但是许多 Docusaurus 站点都弹出了文档相关的组件，并且会想知道它们的自定义可能会破坏 Docusaurus。

如何升级

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

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

可选更改

有些更改不是强制性的，但为了充分利用 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.org.cn',
  // 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、格式化程序、代码检查器等）的兼容性。

在未来的 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 Playground中编译，或者使用npx docusaurus-mdx-checker。
删除 node_modules 和 package-lock.json，然后再次运行 npm install。
运行 docusaurus clear 以清除缓存。
删除可能不支持 Docusaurus v3 的第三方插件。
删除所有您修改的组件。

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

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

提供一个我们可以轻松运行的最小重现示例，理想情况下使用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 基础配置​

新的配置加载器​

警告提示​

版本化侧边栏​

博客 Feed 限制​

文档主题重构​

可选更改​

自动 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 基础配置

新的配置加载器

警告提示

版本化侧边栏

博客 Feed 限制

文档主题重构

可选更改

自动 JSX 运行时

ESM 和 TypeScript 配置

使用 `.mdx` 扩展名

升级数学包

关闭 MDX v1 兼容性

`comments` 选项

`admonitions` 选项

`headingIds` 选项

故障排除