Docusaurus 3.0 发布公告
今天，我们很高兴地宣布 Docusaurus 3.0 发布！🥳
在 Meta 开源，我们相信 Docusaurus 将帮助您以最少的努力构建最佳的文档网站，让您专注于真正重要的事情：编写内容。
这是 Docusaurus 的一个新的主要版本，它带来了令人兴奋的新功能和升级的依赖项。
根据 语义版本控制 原则，此版本包含我们在 v3 升级指南 中详细记录的重大更改。重大更改可能令人烦恼，但它们对于为我们计划实施的新一轮 Docusaurus 功能奠定基础是必要的。
我们最初计划发布更频繁的主要版本，但 Docusaurus v3 的发布时间比预期要长。在我们积累的重大更改中，升级到 MDX v3 可能是采用此新版本的主要挑战。我们竭尽全力使此升级尽可能简单，尤其是在添加了 MDX v1 的兼容性选项。
最简单的站点只需要升级几个 npm 依赖项。对于更复杂的站点，我们提出了一些策略，可以帮助您更自信地进行升级
根据我们的 发布流程，Docusaurus v2 现已进入维护模式。它只会在 3 个月内（截至 2024 年 1 月 31 日）针对重大安全问题提供支持。建议在该时间范围内升级到 v3。
重大更改
本节仅为您提供快速概览。所有重大更改均在 v3 升级指南 中进行了详细记录。
Docusaurus v3 将一些依赖项升级到新的主要版本，每个版本都有其自身的重大更改
- Node.js v16 ➡️ v18
- React v17 ➡️ v18
- MDX v1 ➡️ v3
- TypeScript v4 ➡️ v5
- prism-react-renderer v1 ➡️ v2
- react-live v2 ➡️ v4
- Mermaid v9 ➡️ v10
- import-fresh v3 ➡️ jiti v1
- remark-emoji v2 ➡️ v4
典型的 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"
}
}
除了 MDX v3 之外，这些升级的依赖项带来的大多数重大更改已在内部为您处理：大多数情况下，您无需执行任何操作。在依赖项之外，来自 Docusaurus 代码库的唯一功能性重大更改是
- #9189：新的默认博客 RSS 提要限制为 20 个条目
- #9308：修复并重新引入
:::warning警告，弃用:::caution - #9310：删除旧版本的侧边栏 ID 前缀，用于在
v2.0.0-beta.10（2021 年 12 月）之前进行版本控制的站点 - #7966：重构文档主题组件，最终需要您重新混入它们
亮点
以下是此新版本中一些有用的新功能的非详尽列表。所有功能都列在 Docusaurus v3.0.0 发布说明 中。
Markdown
Docusaurus v3 从 MDX v1 升级到 MDX v3
这个新的 MDX 版本对于内容编写者和插件作者来说要好得多，并为实现令人兴奋的新 Markdown 功能奠定了基础。
从 MDX v1 迁移到 MDX v3 是采用 Docusaurus v3 的主要挑战。
某些在 Docusaurus v2 下成功编译的文档现在可能在 Docusaurus v3 下无法编译，而其他文档的渲染方式可能有所不同。
大多数重大更改来自 MDX v2，而 MDX v3 是一个相对较小的版本。 MDX v2 迁移指南 中有一节介绍如何 更新 MDX 文件，这与我们特别相关。还要确保阅读 MDX 疑难解答 页面，该页面可以帮助您解读常见的 MDX 错误消息。
不要害怕。大多数问题都很容易解决，通常与现在需要转义的 { 和 < 字符有关。但是，根据您网站的大小，您可能需要编辑许多文件并感到不知所措。出于这个原因，我们提供了一个命令 npx docusaurus-mdx-checker 来帮助您估计要完成的工作量，我们建议您 提前准备您的站点。
如果您创建了自定义的 MDX 插件（Remark/Rehype），则 AST 略有不同，您可能需要对其进行重构。
这尤其使我们能够添加一个 CommonMark 模式，这应该使现有的文档更容易采用 Docusaurus。它目前是可选的且实验性的，并且有限制（某些 Docusaurus 功能将无法使用）。在 Docusaurus v3 中，所有文件仍然被解释为 MDX，但我们计划在即将发布的主要版本中将 .md 文件解释为 CommonMark，并建议对使用 JSX 或 ES 模块的任何文件使用 .mdx 扩展名。
我们还引入了一种新的方法来 为您的站点全局配置 Markdown，并计划稍后添加更多灵活的选项。
export default {
markdown: {
format: 'mdx',
mermaid: true,
preprocessor: ({filePath, fileContent}) => {
return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
},
};
Docusaurus 现在使用 remark-directive 插件来支持警告。这也使您可以创建自己的 Remark 插件，以使用您自己的 自定义指令（如 :textDirective、::leafDirective 或 :::containerDirective）扩展 Markdown。
ESM 和 TypeScript 配置
在 #9317 中，我们添加了对 ES 模块和 TypeScript 配置文件的支持，包括站点配置、文档侧边栏、插件和预设。
以下为 2 个 TypeScript 示例，为您提供具有 IDE 自动完成功能的现代体验
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
const config: Config = {
title: 'My Site',
favicon: 'img/favicon.ico',
// your site config ...
presets: [
[
'classic',
{
// your preset config ...
} satisfies Preset.Options,
],
],
themeConfig: {
// your theme config ...
} satisfies Preset.ThemeConfig,
};
export default config;
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: ['introduction'],
};
export default sidebars;
未列出内容
Docusaurus 已经在我们的 3 个内容插件（文档、博客、页面）中支持了 draft: true 前置 matter 选项，这使您可以从生产构建中删除某些页面。
在 #8004 中，我们引入了一个新的 unlisted: true 前置 matter 选项，它将使您的页面在生产构建中可用，同时“隐藏”它们并使它们无法被发现，除非您拥有该 URL。这使您可以轻松地进行工作流，在最终发布之前轻松征求内容反馈。
未列出的内容将
- 从
sitemap.xml中排除 - 由于
<meta name="robots" content="noindex, nofollow" />而从 SEO 结果中排除 - 从博客 RSS 提要中排除
- 从 Algolia DocSearch 结果中排除
- 将从网站导航栏项目、文档侧边栏、博客侧边栏、博客存档、标签页面等中过滤。
未列出的内容也会显示横幅，以便您在内容准备好发布后不要忘记将其关闭。以下是一个未列出的博客文章的示例。
React 18
在#8961中，我们升级到了 React 18。这很重要，特别是对于逐步采用并发 React 功能，以及即将推出的令人兴奋的功能，例如构建时 React 服务器组件。
这个新版本的 React 应该可以作为大多数 Docusaurus 站点的直接替换。它附带了一些我们已在 Docusaurus 代码库中内部处理的重大更改。如果您的站点使用了大量自定义 React 代码，我们建议您查看有关如何升级到 React 18的官方文章，特别是新的自动批处理行为。
React 18 带来了新功能
<Suspense>React.lazy()startTransition()
它们在 Docusaurus 中的支持被视为**实验性**的。我们可能需要在未来调整集成，从而导致不同的运行时行为。
自动 JSX 运行时
Docusaurus 现在使用“自动” JSX 运行时。
不再需要在不使用任何 React API 的 JSX 文件中导入 React。
- import React from 'react';
export default function MyComponent() {
return <div>Hello</div>;
}
调试构建
现在可以以开发模式构建静态站点。
docusaurus build --dev
Docusaurus 将更多错误记录到控制台，特别是通过新的onRecoverableError 回调的 React 18 水合错误。
这种新的构建模式对于**解决 React 问题**特别有用。Docusaurus 将使用 React 的开发版本，从而生成详细且可读的错误消息，而不是指向React 错误解码器页面的压缩错误消息。
TypeScript
Docusaurus v3 现在需要 TypeScript 5.0 的最低版本。
我们将基本推荐的 TypeScript 配置重新内部化到一个新的官方包中
{
- "extends": "@tsconfig/docusaurus/tsconfig.json",
+ "extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
}
}
我们还为 Docusaurus 核心类型、插件和预设选项提供了更简洁、规范化的导出，您可以在全新的TypeScript 配置文件中使用它们。
import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
代码块
在#9316中，我们通过prism-react-renderer v2 升级改进了语法高亮显示。例如，bash 参数--save现在是彩色的。
npm install --save some-package
交互式代码编辑器也升级到react-live v4，并附带了一个新的sucrase编译器。它更快、更轻，并支持现代功能，特别是 TypeScript 类型注释。
function Hello() { const name: string = 'World'; return <div>Hello {name}</div>; }
在#8982和#8870中，我们还添加了对 TeX 类、Haskell 类和 WebAssembly 注释语法的魔法注释支持。
stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs
function result = times2(n)
result = n * 2;
end
x = 10;
y = times2(x);
Mermaid 图表
在#9305中，我们升级到 Mermaid v10.4 并添加了对异步图表渲染的支持。Docusaurus 现在能够渲染新型图表。
思维导图
象限图
查询字符串数据属性
在#9028中，我们使得可以通过docusaurus-data-x查询字符串参数设置自定义 HTML数据属性成为可能。这使得在另一个站点上嵌入 Docusaurus iframe 变得更容易，并允许您使用 CSS 自定义嵌入版本的显示。
html[data-navbar='false'] .navbar {
display: none;
}
html[data-red-border] div#__docusaurus {
border: red solid thick;
}
其他功能
其他值得一提的新功能
- #9189：新的博客
feedOptions.limit选项 - #9071：为页面插件添加规范化的 SEO 前端内容支持
- #9171：客户端重定向插件现在支持目标 URL 中的完全限定 URL 和查询字符串/哈希
- #9171：新的 ESLint 规则
no-html-links - #8384：新的 ESLint 规则
prefer-docusaurus-heading
阅读Docusaurus v3.0.0 发行说明以获取完整的更改列表。
结论
此版本包含一些功能，但更重要的是**升级了 Docusaurus 基础架构的许多部分**。
**MDX 升级**今年花费了我们大量时间，我们努力让这个重要的升级对大家来说不那么困难。
现在我们已经赶上了基础架构，我们将很快在即将发布的次要版本中**提供有用的文档功能**。
感谢大家多年来使用 Docusaurus。文档框架领域最近竞争变得更加激烈，我们将尽最大努力确保 Docusaurus 仍然是一个**具有竞争力的解决方案**，并以其出色的**灵活性**脱颖而出。