标签:

• 发布
• 升级

发布摘要

Docsy 0.13.0 包含以下重要功能与修复：

• 导航与用户体验改进，包括 2025 年 得票最高 的功能请求：目录活动项跟踪（#349、#2289）；
• 重写告警短代码，更好地支持 Markdown；
• 改进无障碍能力，增强颜色对比度和深色模式支持。

准备升级？

• 审阅 BREAKING 变更：
  • 告警短代码正文处理方式变化；
  • 语言菜单可见性变化。
• 可以快速浏览：
  • 新功能；
  • 其他重要变更。
• 准备好后，直接阅读升级到 0.13.0。

导航与用户体验改进

目录活动项跟踪

Docsy 0.13.0 引入 目录（TOC）活动项跟踪，这是 2025 年 得票最高 的功能请求。当读者滚动页面时，当前可见分区对应的目录项会高亮。该功能通过 Bootstrap ScrollSpy 的补丁版本实现。新增的默认目录标签“本页内容”与“返回页首”可以本地化。详情参阅使用 ScrollSpy 跟踪目录活动项。

分区侧边栏根节点

Docsy 0.13.0 引入 sidebar_root_for 配置项，可以把侧边栏导航限制到指定分区。这对需要为不同分区采用不同导航树的大型站点尤其有用，也适用于同时包含非文档分区的纯文档站点。

在页面 Front Matter 中添加 sidebar_root_for 即可启用。支持 children 与 self 两种取值。用法与示例参阅分区侧边栏根节点，实现细节见 #2328 和 PR #2364。

语言菜单可见性

在 Docsy 0.13.0 之前，多语言站点的语言选择菜单会根据视口宽度，在导航栏与侧边栏之间切换：

位置	宽视口	窄视口
导航栏	可见	隐藏
侧边栏	隐藏	可见

可见性由 Bootstrap lg 断点触发，也就是宽窄布局切换的位置。

0.13.0 在所有视口宽度下的新行为如下：

位置	所有视口宽度
导航栏	可见
侧边栏	隐藏

这是一项 BREAKING 用户体验变更。可以通过以下方式恢复旧行为：

• 导航栏：把以下 SCSS（或等效样式）加入项目样式，恢复过去的 d-none d-lg-block 行为：

  .td-navbar__lang-menu {
    @extend .d-none;
    @extend .d-lg-block;
  }
  

• 侧边栏：在站点配置中把可选参数 .ui.sidebar_lang_menu 设为 true。

语言菜单详情见添加语言菜单；实现细节见 #2035、#2001 与 PR #2303。

移动端导航栏滚动提示

导航菜单发生溢出时——主要是在窄视口——导航栏现在会显示左右滚动提示，帮助用户发现更多导航项（#2406）。

告警短代码改进

从 Docsy 0.13.0 起，以 Markdown 形式（{{% alert %}}）调用 alert 时，正文采用新的处理方式：内部 Markdown 直接传给页面 Markdown 渲染器，与页面其余内容一起处理。此前，短代码会在内部调用 Hugo 的 markdownify 函数。

因此，告警现在可以：

• 调用其他短代码，也就是 嵌套短代码；
• 包含页面其他位置定义的链接，或与其他位置 共享链接定义；
• 用在列表等 缩进上下文 中；
• 包含会进入页面目录的 标题（针对 docs 页面）。

详情、示例和重要格式要求见 alert，实现细节见 PR #941。

需要操作：如果 .html 内容文件中使用 alert，而且正文含有 Markdown，则需要调整。

请使用 Hugo 的短代码 Markdown 调用语法：{{% %}}，否则 Markdown 正文可能无法正确渲染。

基本检查：抽查包含 alert 的页面，无论它位于 Markdown 还是 HTML 内容文件中，都要确认渲染符合预期。

无障碍改进

• 主题整体的 颜色对比度 得到改善，Docsy 现在会回退到 Bootstrap 的字体与颜色默认值，从而提供更好的开箱即用无障碍合规性。详情见 #2285 和站点颜色。

• 深色模式的 颜色对比度 改进：

  • 修复用户偏好与系统设置不同时的目录项颜色对比度（#2379）；
  • 为使用 Bootstrap 主题变量的项目提供早期实验性支持，允许定制对比度调整（#2384）。详情见选择具有良好对比度的颜色。EXPERIMENTAL

• 深色模式：

  • 修复无样式内容闪烁（FOUC）（#2332）；
  • Google 搜索 结果页支持深色模式（#2387）。EXPERIMENTAL
  深色模式速查

  如需启用全部深色模式功能（包括实验功能），请在 _styles_project.scss 中加入以下导入。详情见浅色/深色模式。

  // Dark mode enhancements
  @import 'td/color-adjustments-dark';
  @import 'td/code-dark';
  @import 'td/gcs-search-dark';
  

其他重要变更

• 更好的 NPM 支持：通过 NPM 使用 Docsy 的项目不再遇到 Optional 与 Peer Dependency 问题（#2115）。

• 翻译（i18n）：新增奥克语 Locale（#2173），并更新简体中文（#2313）与乌克兰语（#2331）翻译文件。

• 新增 _param 短代码：实验性参数替换短代码，适合生成动态模板内容。详情见 PR #2371。

• 数学与化学公式：Docsy 改用 Hugo 内置 KaTeX 引擎在构建期渲染，mhchem 扩展也已内置。详情见使用 KaTeX 支持 LaTeX（#2276、#2394、#2395）。

  遇到公式时，KaTeX 引擎会自动启用，无需配置；项目可以删除已经过时的 params.katex.* 站点配置，包括 enable、html_dom_element、options 与 mhchem。

升级到 0.13.0

前提条件

我们建议 先阅读 Docsy 0.12.0 升级指南，因为该版本包含重要破坏性变更。

升级流程与 AI 辅助

你是否尝试过用 AI 协助升级 Docsy？它能帮上大忙！

0.12.0 升级指南同时面向项目维护者和 AI 助手编写。事实上，我已经用它成功升级 The Update Framework 等项目的网站。只以升级指南为输入，AI 助手就全自动创建了 TUF PR 126，而我只需要负责审阅。

每次 Docsy 发布都有一些相同升级步骤，例如更新 Docsy NPM 软件包或 Hugo Module。这些步骤已经写在升级到 Docsy 0.12.0中；请照此执行，并把其中的 0.12.0 替换为 0.13.0。本次升级版本如下：

• Docsy：0.12.0 → 0.13.0
  其中 Bootstrap：5.3.6 → 5.3.8
• Hugo：0.147.5 → 0.152.2²

  请注意 Hugo 0.152.0 破坏性变更。

• Node：LTS 22 → LTS 24²

升级后，请审阅破坏性变更，并全面测试站点。测试清单见升级到 Docsy 0.12.0指南。

接下来是什么？

2026 年已经规划了令人期待的增强功能³！

下一版暂定工作项与进度见 0.14.0 发布准备（#2404）。目前得票最高的增强请求包括：

• 仓库/页面元数据链接修复与改进（#1841），尤其是 GitLab 支持（#375）；
• 删除 jQuery（#1436）。

参考资料

关于本版：

• 0.13.0 Changelog 条目
• 0.13.0 发布页
• 0.13.0 发布准备 Issue（#2266）

其他参考资料：

• 0.12.0 升级指南
• 从 Hugo 0.147.5 升级到 0.152.2 时的注意事项：
  • 配套文章 Hugo 0.152.0 破坏性变更
  • 官方 Hugo 发布说明

• ←上一页
• 下一页→