Docusaurus 3.1

我们很高兴地宣布发布 Docusaurus 3.1。

升级应该很简单：如我们的 发布流程文档 中所述，次要版本遵循 语义版本化。

亮点

断开的锚点检查器

在 #9528 中，我们改进了内置的断开链接检查器，使其也能够检测断开的锚点。

快速失败

新的 onBrokenAnchors 选项默认值为 warn，出于向后兼容性原因。

我们建议将其更改为 throw，并在将断开的锚点部署到生产环境之前让 CI 构建失败。

注意

对于实现自定义 <Heading> 和 <Link> 组件的用户和插件作者，我们提供了一个新的 useBrokenLinks React 钩子 API。

大多数 Docusaurus 用户无需关心它，内置组件（docusaurus/Link 和 @theme/Heading）已在内部使用它。

parseFrontMatter 钩子

在 #9624 中，我们添加了一个新的 siteConfig.markdown.parseFrontMatter 函数钩子。

这使得您可以实现方便的前置数据转换、快捷方式，或使用 Docusaurus 插件不支持的前置数据与外部系统集成。

docusaurus.config.js

export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

阅读 前置数据指南 和 parseFrontMatter API 参考 以了解更多详细信息。

其他更改

其他值得注意的更改包括

• #9674：添加 siteConfig.markdown.remarkRehypeOptions 以将选项传递给 remark-rehype，让您可以自定义诸如 MDX 脚注标签之类的内容
• #9671：添加 (Visual) Basic/Batch/Fortran/COBOL/ML 代码块 MagicComments 支持
• #9610：通过 PORT 环境变量启用 CLI 端口配置
• #9477：完成巴西葡萄牙语 (pt-BR) 翻译

查看 3.1.0 变更日志条目 以获取完整的更改列表。