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() 钩子。这使用户能够使用自己的自定义逻辑创建/过滤/转换/增强站点地图项。

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 中，我们通过添加一些与编辑 URL 和 Markdown 页面底部显示的最后更新元数据相关的缺少的页面插件 API，标准化了每个核心内容插件上可用的选项。

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 完全控制 React 页面的布局。

其他更改

其他值得注意的更改包括

• #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 版本变更日志条目 以获取完整的更改列表。