版本：3.8.1

升级到 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 风格的 Markdown (GFM)，但 MDX 不再支持使用<link>语法的自动链接。

example.md
<[email protected]>

<https://:3000>

错误消息

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

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

如何升级

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

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

https://:3000
[https://:3000](https://: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 输出
<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>

您也可以用{和}包裹此类内容，以避免额外的<p>标签，如果您不打算在那里使用 Markdown 语法的话。

-<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开头的字符在此处被视为标点符号。

如何升级

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

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

一个非官方的 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 */
};

如果您想继续使用 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重新内部化到我们的新 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，它以红色渲染。

警告

这是一个 Docusaurus v2 :::warning 忠告。

然而，颜色和图标一直都是错的。Docusaurus v3 正式重新引入了:::warning忠告，对其进行了文档化，并修复了颜色和图标。

警告

这是一个 Docusaurus v3 :::warning 忠告。

如何升级

如果您以前使用过未记录的:::warning忠告，请务必检查每次使用时黄色是否是合适的颜色。如果您想保留红色，请改用:::danger。

Docusaurus v3 还废弃了:::caution忠告。请将:::caution（黄色）重构为:::warning（黄色）或:::danger（红色）。

如果您想保留“caution”标题，您可能需要将其重构为:::warning[caution]（黄色）。

版本化侧边栏

此破坏性变更将仅影响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"
  ]
}

如何升级

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

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

博客 Feed 限制

@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.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、格式化程序、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创建的
提供一个展示问题的实时部署网址（如果您的站点可以构建）
清晰地解释问题，而不仅仅是模糊的“它不起作用”
包含尽可能多的相关材料：代码片段、仓库网址、git 分支网址、完整堆栈跟踪、屏幕截图和视频
清晰、简洁地提出您的请求，向我们表明您已努力帮助我们帮助您

另外，您可以寻找付费的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` 选项

故障排除