发布 Docusaurus 3.0
今天，我们很高兴地 宣布 Docusaurus 3.0！🥳
在 Meta Open Source，我们相信 Docusaurus 将帮助您以最少的精力构建最佳文档网站，让您专注于真正重要的事情：编写内容。
这是 Docusaurus 的一个新主要版本，带来了令人兴奋的新功能和升级的依赖项。
遵循 Semantic Versioning 原则，此版本包含重大更改，我们已在 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 feed 限制为 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 插件，以使用自己的 自定义指令扩展 Markdown，例如 :textDirective、::leafDirective 或 :::containerDirective。
ESM 和 TypeScript 配置
在 #9317 中，我们增加了对 ES 模块和 TypeScript 配置文件的支持，包括站点配置、文档侧边栏、插件和预设。
以下是两个 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 已经支持在我们的三个内容插件（docs、blog、pages）中，draft: true 这个 front matter 选项，它允许您从生产构建中移除某些页面。
在 #8004 中，我们引入了一个新的 unlisted: true front matter 选项，它将使您的页面在生产构建中可用，但会“隐藏”它们，除非您拥有 URL，否则无法被发现。这使得在最终发布之前轻松征求内容反馈的工作流程成为可能。
未列出内容将
- 从
sitemap.xml中排除 - 由于
<meta name="robots" content="noindex, nofollow" />而从 SEO 结果中排除 - 从博客 RSS feeds 中排除
- 从 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 水合（hydration）错误。
这种新的构建模式对于解决 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 front matter 支持
- #9171：客户端重定向插件现在支持目标 URL 中的完整 URL 和查询字符串/哈希
- #9171：新的 ESLint 规则
no-html-links - #8384：新的 ESLint 规则
prefer-docusaurus-heading
阅读 Docusaurus v3.0.0 发布说明以获取完整的更改列表。
总结
此版本带来了一些功能，但更重要的是升级了 Docusaurus 基础设施的许多部分。
此MDX 升级今年花费了我们大量时间，我们努力让这次重要的升级对大家来说不那么困难。
既然我们已经赶上了基础设施的步伐，我们将很快在即将发布的次要版本中提供有用的文档功能。
我们感谢您多年来使用 Docusaurus。文档框架领域最近变得更具竞争力，我们将尽最大努力确保 Docusaurus 仍然是一个有竞争力的解决方案，以其卓越的灵活性脱颖而出。