Docusaurus v3 现在 处于测试阶段，官方发布即将到来。这是为这个新主要版本准备你的网站的最佳时机。

Docusaurus v3 带来了一些重大变化，其中许多可以在Docusaurus v2 下处理。提前准备你的网站可以逐步完成，并且将使升级到 v3 更加容易。

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

本文将主要关注如何为这个新的MDX版本准备您的内容，并将列出一些您现在可以处理的其他重大更改。

准备工作​

在准备升级到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游乐场​

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

每个MDX版本都附带自己的游乐场：

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

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

使用MDX检查器CLI​

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

npx docusaurus-mdx-checker

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

常见的MDX问题​

我们将一些Docusaurus站点升级到了Docusaurus v3和MDX v3：

• Docusaurus PR
• React-Native PR
• Jest PR

这些升级使我们能够汇总最常见的内容问题，并记录如何最好地处理它们。

错误使用 {​

{ 字符用于打开 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中，现在可以更轻松地交错使用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');
```

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 {
    // 站点配置...
  };
};

其他重大变更​

除了MDX之外，还有其他重大变更，您可以提前为您的网站做好准备，特别是重要依赖项的主要版本升级。

Node.js 18.0​

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

React 18.0​

Docusaurus v3 现在需要 React >= 18.0。

React 18 带来了自己的重大变化，这些变化应该相对容易处理，具体取决于您为网站创建的自定义 React 代码的数量。

仅使用我们官方主题代码而不进行swizzling的简单Docusaurus站点无需做任何事情。

TypeScript 5.0​

Docusaurus v3 现在需要 TypeScript >= 5.0。

TypeScript 基础配置​

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

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

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

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

警告提示​

由于历史原因，我们支持一个未记录的警告 :::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 v3​

Docusaurus v3 现在处于测试阶段，并且已经被React-Native、Jest和我们自己的网站用于生产环境。

我们认为这个新版本的Docusaurus非常稳健，已经准备好投入生产环境。在收到我们社区早期采用者的积极反馈后，它应该很快就会正式发布。

如果您尝试升级并在3.0.0-beta.0 发布讨论线程上报告问题，我们将非常感激。

对于大多数网站来说，升级应该很容易。如果您按照这里的文档提前准备了您的网站，升级以下依赖项应该就足够了：

 {
   "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 v3 - 升级支持
• Docusaurus v3 - Discord 频道 #migration-v2-to-v3
• MDX v3 - 升级支持
• MDX v3 - Remark/Rehype 插件支持
• MDX v3 - Discord 频道 #migration-mdx-v3

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

结论​

Docusaurus v3 已经准备好试用，并将很快发布。本文已经为您提供了升级所需的所有主要更改的概述。

初始的3.0版本主要关注依赖性和基础设施的升级，这将使我们能够实现新的令人兴奋的功能。它还附带了一些有用的功能，我们将在最终发布说明中详细介绍。