本文档将帮助您将站点从Docusaurus v2升级到Docusaurus v3。

Docusaurus v3 是一个新的主要版本，包含重大变更，需要您相应地调整您的网站。我们将在此过程中为您提供指导，并提及一些可选的建议。

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

主要的重大变化是从MDX v1升级到MDX v3。请阅读MDX v2和MDX v3的发布说明以获取详细信息。MDX现在将更严格地编译您的Markdown内容，并且会有细微的差异。

升级依赖​

升级到 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+

一个典型的 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用户：

 {
   "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下无法编译。

其他文档可能也会呈现不同。

升级MDX会带来所有在MDX v2和MDX v3发布博客文章中记录的重大变更。大多数重大变更来自MDX v2，而MDX v3是一个相对较小的发布。MDX v2迁移指南中有一个关于如何更新MDX文件的部分，这对我们特别相关。同时，请务必阅读MDX故障排除页面，它可以帮助你解释常见的MDX错误信息。

请务必阅读我们更新的MDX 和 React文档页面。

使用MDX游乐场​

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

• MDX 游乐场 - 当前版本
• MDX 游乐场 - v1

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

使用MDX检查器CLI​

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

npx docusaurus-mdx-checker

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

常见的MDX问题​

Docusaurus 无法详尽地记录 MDX 带来的所有变化。这是 MDX v2 和 MDX v3 迁移指南的责任。

然而，通过升级几个Docusaurus站点，我们注意到大多数问题归结为我们为您记录的少数几种情况。

错误使用 {​

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

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

<的错误使用​

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

Use Android version <5

You can use a generic type like Array<T>

Follow the template "Road to <YOUR_MINOR_VERSION>"

GFM自动链接的错误使用​

Docusaurus 支持 GitHub Flavored Markdown (GFM)，但 MDX 不再支持使用 语法的 autolink。

<[email protected]>

<http://localhost:3000>

[email protected]
[[email protected]](mailto:[email protected])

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

小写 MDXComponent 映射​

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

• 一个 MDXComponent 映射仅用于 # hi 而不用于

  hi

• 一个小写的自定义元素名称将不再由其相应的MDXComponent组件替换

 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => 

-  myElement: (props) => 
,
+  MyElement: (props) => 
,
 };

意外的额外段落​

在MDX v3中，现在可以更轻松地交错使用JSX和Markdown，而无需额外的换行符。在多行上编写内容也可以生成新的预期

<div>一些 **Markdown** 内容div>
<div>
  一些 **Markdown** 内容
div>

<div>一些 **Markdown** 内容div>
<div>一些 **Markdown** 内容div>

<div>一些 <strong>Markdownstrong> 内容div>
<div><p>一些 <strong>Markdownstrong> 内容p>div>

 

   
-  
-    我的图片说明
-  
+  
 

指令的意外使用​

Docusaurus v3 现在使用 Markdown Directives（通过 remark-directive 实现）作为一种通用方式来支持 admonitions 和其他即将推出的 Docusaurus 功能。

This is a :textDirective

::leafDirective

:::containerDirective

Container directive content

:::

AWS re:Invent 会议很棒

AWS re
会议很棒

不支持的缩进代码块​

MDX 不再将缩进文本转换为代码块。

    console.log("hello");

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

其他Markdown不兼容性​

强调以空格或标点符号开头或结尾​

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

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

**（除了`**`）在以下示例中在Docusaurus 2中被正确解析，但在Docusaurus 3中不再如此。

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

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

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

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

MDX 插件​

MDX生态系统中的所有官方包（Unified、Remark、Rehype...）现在都仅支持ES模块，不再支持CommonJS。

实际上，这意味着你不能再做require("remark-plugin")了。

import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* 在此处使用 Remark 插件的站点配置 */
};

module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // 站点配置...
  };
};

格式化工具​

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：

*.mdx

其他重大变更​

除了MDX v3升级外，以下是Docusaurus v3带来的详尽破坏性更改列表。

Node.js v18.0​

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

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

React v18.0+​

Docusaurus v3 现在需要 React >= 18.0。

React 18 带来了其自身的重大变化，这些变化应该相对容易处理，具体取决于您为网站创建的自定义 React 代码量。官方主题和插件与 React 18 兼容。

Prism-React-Renderer v2.0+​

Docusaurus v3 将 prism-react-renderer 升级到 v2.0+。该库用于代码块的语法高亮显示。

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

- 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;

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

React-Live v4.0+​

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

remark-emoji v4.0+​

Docusaurus v3 将 remark-emoji 升级到 v4.0+。这个库用于支持 Markdown 中的 :emoji: 快捷方式。

Mermaid v10.4+​

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

TypeScript v5.1+​

Docusaurus v3 现在需要 TypeScript >= 5.1。

 {
   "devDependencies": {
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

TypeScript 基础配置​

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

这个新包的版本与所有其他Docusaurus核心包的版本保持一致，并将用于确保TypeScript的向后兼容性以及在主要版本升级时的破坏性更改。

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

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

新配置加载器​

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

警告提示​

由于历史原因，我们支持一个未记录的警告 :::warning，它以红色呈现。

然而，颜色和图标一直有误。Docusaurus v3 正式重新引入了 :::warning 警告提示，并对其进行了文档化，同时修复了颜色和图标。

版本化侧边栏​

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

在创建版本 v1.0.0 时，侧边栏文件包含了一个前缀 version-v1.0.0/，该前缀 Docusaurus v3 不再支持。

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

{
  "docs": ["introduction", "prerequisites"]
}

博客订阅限制​

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

const blogOptions = {
  feedOptions: {
    limit: false,
  },
};

文档主题重构​

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

从技术上讲，这不是一个破坏性更改，因为这些组件被标记为不安全以进行混用，然而许多Docusaurus站点弹出了与文档相关的组件，并且会感兴趣知道他们的自定义可能会破坏Docusaurus。

可选更改​

一些更改并非强制性的，但了解它们仍然有助于充分利用 Docusaurus v3。

自动 JSX 运行时​

Docusaurus v3 现在使用 React 18 的 "自动" JSX 运行时。

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

- import React from 'react';

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

ESM 和 TypeScript 配置​

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

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

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"
}

关闭 MDX v1 兼容性​

Docusaurus v3 提供了 MDX v1 兼容性选项，默认情况下是开启的。

export default {
  markdown: {
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

comments 选项​

此选项允许在MDX中使用HTML注释，尽管HTML注释已不再正式支持。

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

admonitions 选项​

此选项允许使用 Docusaurus v2 admonition title 语法：

:::note Your Title

content

:::

Docusaurus 现在使用 Markdown Directives（通过 remark-directive 实现）来实现 admonitions，提供指令标签的语法需要方括号：

:::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 的第三方插件
• 删除所有你的swizzled组件

一旦你尝试过，你可以通过以下支持渠道寻求帮助：

• Docusaurus v3 - 升级支持
• Docusaurus v3 - Discord 频道 #migration-v2-to-v3
• MDX v3 - 升级支持
• MDX v3 - Remark/Rehype 插件支持
• MDX v3 - Discord 频道 #migration-mdx-v3

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

• 提供一个我们可以轻松运行的最小化复现，最好使用docusaurus.new创建
• 提供一个实时部署的URL，展示问题在实际中的表现（如果您的站点可以构建）
• 清楚地解释问题，而不仅仅是含糊其辞的“它不起作用”
• 尽可能包含相关材料：代码片段、仓库URL、Git分支URL、完整堆栈跟踪、截图和视频
• 清晰地、简洁地呈现你的请求，向我们展示你已经努力帮助我们帮助你

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