Docusaurus 3.1

我们很高兴宣布 Docusaurus 3.1。

升级应该很容易：正如我们在发布流程文档中解释的，次要版本遵循语义化版本控制。

亮点

断链锚点检查器

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

使其快速失败

出于向下兼容的考虑，新的 onBrokenAnchors 选项默认值为 warn。

我们建议将其设置为 throw，让您的 CI 构建失败，而不是将断链锚点部署到生产环境。

注意

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

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

parseFrontMatter 钩子

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

这使得实现便捷的 Front Matter 转换、快捷方式，或与使用 Docusaurus 插件不支持的 Front Matter 的外部系统集成成为可能。

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

有关详细信息，请阅读 Front Matter 指南 和 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 变更日志条目 获取完整的变更列表。