跳到主要内容

Docusaurus 2.4

· 阅读需 5 分钟
Sébastien Lorber
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

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

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

Docusaurus 博客文章社交卡片

亮点​

侧边栏项目描述​

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

sidebars.js
[
  {
    type: 'link',
    label: '带有描述的链接',
    href: 'https://docusaurus.io',
    description: '一些链接描述',
  },
  {
    type: 'category',
    label: '带有描述的类别',
    description: '一些类别描述',
    items: [],
  },
];

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

显示带有自定义描述的侧边栏类别生成的索引

主题查询字符串​

在 #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 的一流支持以及注册生成新选项卡的自定义转换器的能力。

运行这些命令！

```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 错误原因 ）。

提示

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

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

Docusaurus 导航栏错误消息屏幕截图

翻译​

我们实现了对一些新元素进行翻译：

  • #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 更新日志条目 以获取所有更改的详尽列表。