Docusaurus 3.3

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

升级应该很容易。我们的 发布流程 遵循 语义版本控制 。次要版本不包含任何重大更改。

亮点

为 React 19 做准备

React 核心团队最近 发布了第一个 React 19 beta 版本 。他们还 发布了升级指南和 React v18.3 版本 ，其中包含新的警告，以帮助我们在 升级到 React 19 之前 识别问题。

Docusaurus v3 依赖于 React 18.x。初始化新的 Docusaurus 站点时，它将使用新的 React 18.3 版本。如果您决定升级依赖项或重新生成包管理器锁文件，情况也是如此。

事实证明，在当前状态下， Docusaurus 有几个额外的警告需要修复 ，尤其是在任何页面加载和导航时都会立即出现在您的开发控制台上的警告：

警告：LoadableComponent 使用已不再支持的旧版 contextTypes API，该 API 将在下个主要版本中删除。请改用 React.createContext() 和静态 contextType。

在 #10079 中，我们使 Docusaurus 准备好用于 React 19。我们修复了遇到的所有 React 18.3 警告。如果您遇到任何遗漏的警告，请随时 报告新的警告 ，不仅告诉我们，也告诉其他 Docusaurus 第三方插件作者。

createSitemapItems

在 #10083 中，我们在站点地图插件中引入了一个新的灵活的 createSitemapItems() hook。这使用户能够使用他们自己的自定义逻辑来创建/过滤/转换/增强站点地图项。

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        sitemap: {
          createSitemapItems: async ({
            defaultCreateSitemapItems,
            ...params
          }) => {
            const items = await defaultCreateSitemapItems(params);
            return items.filter((item) => !item.url.includes('/tags/'));
          },
        },
      },
    ],
  ],
};

页面插件改进

Docusaurus 页面插件 在可用功能方面一直落后于文档和博客插件。

在 #10032 中，我们通过添加一些缺失的页面插件 API（与编辑 URL 和在 Markdown 页面底部显示的最后更新元数据相关）来规范每个核心内容插件上可用的选项。

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        pages: {
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/website/src/pages',
          editLocalizedFiles: true,
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
        },
      },
    ],
  ],
};

/examples/markdownPageExample

仅适用于 Markdown 页面

这些新的插件选项仅适用于 Markdown 页面，对 React 页面无效，因为您可以完全控制 JSX 的布局。

其他更改

其他值得注意的更改包括：

• #10064 ：新的站点配置选项 siteConfig.markdown.anchors.maintainCase
• #9767 ：新的 docusaurus deploy --target-dir 选项
• #10042 ：新的（实验性）插件 API：route.props
• #10060 ：优化了 App 入口点，避免了导航时无用的重新渲染
• #10080 ：<Admonition> 组件可以正确渲染而无需标题/图标
• #10091 ：<Tabs> 属性现在可以覆盖默认值
• #10090 ：docusaurus serve 与 /baseUrl/ 路径名前缀配合使用效果更好
• #10070 ：添加了 pt-BR 缺少的主题翻译
• #10025 ：文档侧边栏项目标签现在会影响文档分页标签

查看 3.3.0 更新日志条目 以获取所有更改的详尽列表。