Docsy 0.9.0 发布报告

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

以 Docsy 的发布规模衡量，Docsy 0.9.0 是一次相当可观1的更新（包含 65 个以上 PR），其中有若干值得特别说明的破坏性和重要变更，主要涉及：

感谢所有贡献者！

本版全部 Footer 改进与修复见 #1818。本节选取其中几项介绍。为了让定制更加容易，我们还为下一个主要版本规划了更多 Footer 改进（#1852）。

为简化定制，Footer 布局被拆分为左、右、中三个部分（#1500），其中版权又是中间部分的子组件（#1817）。每一部分都有独立 class，例如 td-footer__left，便于定制样式。请注意，td-footer__copyright-etc 已重命名为 td-footer__center。

太好了！我们终于关闭了 Issue #2！

本版解决了 Docsy 存在时间最长、也是项目创建的第一个 Issue：

Footer 版权现在支持年份范围，并可以回退到站点版权配置：

  • Hugo 配置 params.copyright 过去只能是字符串，现在也可以是包含 authors、from_year、to_year 等可选字段的 Map。to_year 未设置时，默认为站点构建年份；authors 默认为“<Site.Title> Authors”，并按 Markdown 渲染；
  • params.copyright 未设置时，会使用站点 copyright 配置，并将其按 Markdown 原样渲染，不会附加日期。

  • About 页面链接默认隐藏。如需启用，请在项目配置中把 .params.ui.footer_about_enable 设为 true。.params.ui.footer_about_disable 已弃用；

  • “保留所有权利”文本默认隐藏。如需显示，请在 _styles_project.scss 项目样式文件中加入以下规则（必要时可添加 !important，示例未写）：

    .td-footer__all_rights_reserved {
  display: inline;
}

仓库链接及其他页面信息

从 2019 年起，如何正确生成仓库链接一直困扰着 Docsy 维护者与贡献者（#138）。难点在于，无论下游项目使用单语言还是多语言、是否设有首页，链接都必须正确工作。

最终，指导委员会成员 Lisa 的坚持取得了成果。Lisa 半开玩笑地说：我们只花了几年时间，又等来了几项 Hugo 改进。 确实，直到 2023 年 5 月发布的 Hugo 0.112.0 提供必要函数后，问题才得以解决。详情请参阅：

我们相信 Lisa 的修复已经彻底消灭仓库链接缺陷。

正如 CHANGELOG 所述，对于使用 Mount 且页面配置了 path_base_for_github_subdir 的站点，这是一项 破坏性变更。

从仓库/页面元数据链接修复与改进（#1841）可以看到，仍有若干问题尚待解决。不过，修复 #1744 已经为后续工作奠定必要基础。#1841 中列出的问题将在未来版本中通过进一步重构与扩展布局解决。

页面最后修改信息

可以配置站点，在文档和博客页底部显示页面源码的最后修改元数据。详情参阅用户指南新增的页面最后修改元数据一节。

外观与风格

Docsy 改为通过 Hugo render-heading.html 钩子在构建期生成标题自链接，取代由 assets/js/anchor.js 在客户端渲染的旧实现（该文件在 #1460 中删除）。项目现在必须显式启用此功能，详情见标题自链接。

默认自链接符号过去是嵌入式 SVG，现在改由 CSS 定义为网站常用的 #。项目可以通过 .td-heading-self-link class 定制外观。

标题自链接现在：

  • 在移动端和触控设备上始终可见；
  • 在其他设备和屏幕上，仍与过去一样，只在鼠标悬停到标题上时显示。

Docsy 现在遵循推荐的 无障碍实践：页面正文中的 链接默认带下划线。详情见 #1814 与 #1815。

再见，省略号

blocks/feature 短代码的“阅读更多”链接文本后不再自动附加省略号（“……”）。希望恢复省略号的项目，可以在站点各语言的 "ui_read_more" 语言参数中自行加入（#1820）。

持续集成测试

为保障 Docsy 的质量与稳定性，本版通过 GitHub Actions 引入了期待已久的开发者功能：持续集成（CI）测试。

每个 PR 以及主分支提交都会触发以下工作流：

  • 在 Linux 与 Windows 上运行跨平台测试；
  • 执行构建测试，确保 Docsy 及其用户指南成功构建，并通过链接校验等检查；
  • 从零构建 Docsy 站点的烟雾测试，同时验证 Docsy 作为 Hugo Module 与 NPM Module 的用法。

由于访问 Windows 环境的条件有限，Windows 支持采用尽力而为原则；即便如此，跨平台测试仍有助于更早发现潜在构建问题。

这项工作是提高主题可靠性的重要一步。未来我们计划扩大测试覆盖率（#726）。

参考资料与后续版本

本版完整变更清单见 0.9.0 发布条目以及 0.9.0 发布准备（#1759）。

Docsy 接下来会有哪些改进？下一版暂定工作项见 0.10.0 发布准备（#1812）。

0.10.0 及后续版本的功能和修复候选项，目前包括为重新引入 RTL 支持而继续推进 Bootstrap 工作，具体如下：

  1. 这里的“可观”以 Docsy 发布的一贯规模为参照。 ↩︎

最后修改 2026年8月9日 · ci: deploy Pages from main (4f3eb57)