Docusaurus 3.4

我们很高兴地宣布 Docusaurus 3.4。

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

亮点

标签文件

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

使用 #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

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

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 文件分发成为可能，以便读者可以在脱机状态下浏览它，而无需在他们的计算机上安装任何复杂的东西，除了一个 Web 浏览器。

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

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

实验性

此功能是 实验性 的。如果您尝试使用它，请告诉我们它对您有效 这里.

站点存储 - 实验性

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

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

• 在处理多个 http://localhost: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：修复 docs 生成的索引类别卡片描述中的错误复数形式
• #10130：修复由于尾部斜杠导致的损坏的锚点检查器报告的误报

查看 3.4.0 变更日志条目，以获取所有更改的详尽列表。