Docusaurus 3.4

我们很高兴地宣布 Docusaurus 3.4。

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

亮点

标签文件

文档和博客插件都已支持tags front matter 属性，允许您对相关内容进行分组。但是，在 front matter 中内联声明标签并不总是理想的。

通过#10137，您现在可以在tags.yml文件中声明预定义标签列表

blog/tags.yml

tag1:
  label: 'Tag 1'
  description: 'Tag 1 description'
  permalink: /tag-1-permalink

tag2:
  label: 'Tag 2'
  description: 'Tag 2 description'
  permalink: /tag-2-permalink

这些预定义标签可以在您的博客或文档文件的 front matter 中使用

blog/2024-05-31-my-blog-post.md

---
tags: [tag1, tag2]
---

# Title

Content

保持标签使用的一致性

使用新的onInlineTags: 'throw'插件选项来强制使用预定义标签，并防止贡献者创建不需要的新标签。

哈希路由 - 实验性

通过#9859，我们添加了一个新的实验性哈希路由配置选项，对于通过file://协议在本地打开网站进行离线浏览非常有用。

docusaurus.config.js

export default {
  future: {
    experimental_router: 'hash',
  },
};

警告

此模式不推荐用于通过 Web 服务器部署的网站。

当此模式开启时，Docusaurus 将选择不进行静态站点渲染，并构建一个客户端单页应用程序，其中所有路由都以/#/为前缀。将生成一个单独的index.html文件。通过简单地点击此文件，使用浏览器file://协议，即可在本地浏览器中打开它。这使得将 Docusaurus 站点作为.zip文件分发成为可能，以便读者可以离线浏览它，而无需在计算机上安装任何复杂的东西，除了一个网络浏览器。

尝试浏览我们使用哈希路由构建的 Docusaurus 网站

• Docusaurus 网站 - 哈希路由 Web 部署
• Docusaurus 网站 - 哈希路由可下载的 GitHub artifacts

实验性

此功能为实验性。如果您尝试使用，请在此处告知我们您的使用体验。

站点存储 - 实验性

Docusaurus 使用浏览器localStorage API 来持久化 UI 状态。

但有时存储空间在多个使用相同域名的站点之间“共享”，导致存储键冲突。这通常发生在两种情况下：

• 在多个https://:3000站点上工作时
• 在同一域名下托管多个站点时：https://example.com/site1/和https://example.com/site2/

出于这个原因，我们引入了一个新的实验性siteStorage配置选项

export default {
  future: {
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
  },
};

当设置namespace: true时，我们会为所有存储键应用一个哈希后缀，使其对当前站点唯一（基于config.url和config.baseUrl）。例如，theme存储键变为theme-x6f。也可以提供您自己的自定义后缀namespace: 'suffix'。我们还使得可以使用type: 'sessionStorage'而不是默认的localStorage。

实验性

此功能为实验性。如果您尝试使用，请在此处告知我们您的使用体验。

其他更改

其他值得注意的更改包括

• #10151：添加土库曼语 (tk) 主题翻译
• #10111：添加保加利亚语 (bg) 主题翻译
• #10168：修复了许多长期未解决的 Markdown 链接解析错误
• #10178：/search页面现在尊重contextualSearch: false设置
• #10118：修复文档生成索引类别卡片描述中的复数错误
• #10130：修复由于尾部斜杠导致损坏的锚点检查器报告的误报

请查看3.4.0 变更日志条目以获取所有变更的完整列表。