跳至主要内容

Docusaurus 2.4

·阅读 4 分钟
Sébastien Lorber
Sébastien Lorber
Docusaurus 维护者，《本周 React》编辑

我们很高兴地宣布 Docusaurus 2.4。

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

Docusaurus blog post social card

亮点​

在 #8236 中，我们实现了为类型为 link 和 category 的文档侧边栏项目提供新的 description 属性的功能。

sidebars.js
[
  {
    type: 'link',
    label: 'Link with description',
    href: 'https://docusaurus.org.cn',
    description: 'Some link description',
  },
  {
    type: 'category',
    label: 'Category with description',
    description: 'Some category description',
    items: [],
  },
];

这些描述将在类别生成的索引页面中使用。

Show sidebar category generated index with custom descriptions

主题查询字符串​

在 #8708 中，我们添加了通过新的 docusaurus-theme 查询字符串参数强制 Docusaurus 以 light 或 dark 模式初始化自身的功能。

这对于在将现有的 Docusaurus 页面嵌入 iframe 或 WebView 时确保一致的主题很有用。

/docs/?docusaurus-theme=light
/docs/?docusaurus-theme=dark

Remark 插件 npm2yarn 升级​

在 #8690 中，我们升级了我们的 Remark 插件 @docusaurus/remark-plugin-npm2yarn，其中包含许多转换错误修复、对 pnpm 的一流支持以及注册生成新选项卡的自定义转换器的功能。

Run these commands!

```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```
http://localhost:3000
npm install
npm run build
npm run myCustomScript -- --some-arg

支持多个跟踪 ID 的 gtag​

在 #8620 中，我们添加了对 @docusaurus/plugin-google-gtag 插件声明多个跟踪 ID 的支持。

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        gtag: {
          trackingID: [
            'G-<YOUR-NEW-GA4-ID>',
            'UA-<YOUR-OLD-UA-ID>',
          ],
        },
      },
    ],
  ],
};
Google 即将停止使用 Universal Analytics

Google 将于 2023 年 7 月 1 日停止使用其 Universal Analytics。

Docusaurus 用户应迁移到 Google Analytics 4。Google **不允许将您现有的 Universal Analytics 数据迁移**到您的新 Google Analytics 4 属性。

为了保持分析的连续性，我们暂时建议您同时向两个跟踪 ID 报告事件：旧的 (UA-*) 和新的 (G-*)。有关详细信息，请参阅 专用问题。

开发者体验​

在 #8736 中，我们改进了错误消息的渲染方式，并添加了对渲染错误完整因果链的初始支持（请参阅 ES2022 Error Cause）。

提示

要查看其运行情况，请点击此处

在 #8735 中，我们还使与导航栏相关的错误消息更清晰，以帮助用户了解他们做错了什么。

Docusaurus navbar error message screenshot

翻译​

我们实现了翻译一些新元素的功能

  • #8677 引入了一个新的 process.env.DOCUSAURUS_CURRENT_LOCALE（实验性）允许您本地化您的配置文件，包括站点标题、标语、公告栏、baseUrl 等。
  • #8616 允许翻译导航栏和页脚徽标的替代文本

我们添加了对多种语言的默认主题翻译支持

  • 🇭🇺 #8668：匈牙利语
  • 🇳🇴 #8631：挪威语（书面挪威语）
提示

完成主题翻译是一项 持续进行的工作，也是为 Docusaurus 做贡献的一种简单方法。我们定期添加新的主题功能，这些功能通常 需要新的翻译。

其他更改​

其他值得注意的更改包括

  • #8674：尊重 prefers-reduced-motion: reduce 媒体查询
  • #8712：在模板中使用类型为 docSidebar 的导航栏项目
  • #8801：允许选项卡子级为假值
  • #8757：使搜索页面对外部查询字符串更改做出反应
  • #8803：修复 RTL 中的代码块按钮位置
  • #8615：使用深色导航栏时修复颜色模式切换
  • #8699：修复导航栏下拉选项卡焦点错误

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