# Docsy 0.9.0 发布报告

LLMS index: [llms.txt](/oink.pgsty.com/llms.txt)

---

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

- [Footer 改进](#footer)
- [仓库链接及其他页面信息](#page-meta)
- [外观与风格](#look-and-feel)
- [持续集成测试](#ci)

感谢所有[贡献者][0.9.0]！

## Footer 改进 {#footer}

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

### Footer 布局变更 {#footer-layout}

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

### Footer 版权年份范围及其他改进 {#footer-copyright}

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

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

- [Footer 应支持更灵活的版权声明（#2）][#2]，由 [@sarahmaddox][] 提出。

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

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

[站点 `copyright`]: https://gohugo.io/methods/site/copyright/

### 精简 Footer {#footer-streamlined}

- About 页面链接默认隐藏。如需启用，请在项目配置中把
  `.params.ui.footer_about_enable` 设为 true。`.params.ui.footer_about_disable`
  已弃用；
- “保留所有权利”文本默认隐藏。如需显示，请在 `_styles_project.scss`
  [项目样式文件][]中加入以下规则（必要时可添加 `!important`，示例未写）：

  ```scss
  .td-footer__all_rights_reserved {
    display: inline;
  }
  ```

[项目样式文件]: /zh/docs/content/lookandfeel/#project-style-files

## 仓库链接及其他页面信息 {#page-meta}

### 仓库链接 {#repository-links}

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

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

- [修复单语言站点链接（#1744）][#1744]
- [Hugo v0.112.0——新增模板函数][tmpl-func]，作者 [@jmooring][]

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

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

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

### 页面最后修改信息 {#last-modified-page-info}

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

[页面最后修改元数据]:
  /zh/docs/content/repository-links/#last-modified-page-metadata

## 外观与风格 {#look-and-feel}

### 标题自链接 {#heading-self-links}

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

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

标题自链接现在：

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

[标题自链接]: /zh/docs/content/navigation/#heading-self-links

### 无障碍：链接添加下划线 {#accessibility-links-are-underlined}

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

### 再见，省略号 {#bye-bye-ellipsis}

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

## 持续集成测试 {#ci}

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

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

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

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

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

[#726]: https://github.com/google/docsy/issues/726
[工作流]: https://github.com/google/docsy/blob/main/.github/workflows

## 参考资料与后续版本 {#references-and-future-releases}

本版完整变更清单见 [0.9.0][] 发布条目以及
[0.9.0 发布准备（#1759）](https://github.com/google/docsy/issues/1759)。

Docsy 接下来会有哪些改进？下一版暂定工作项见
[0.10.0 发布准备（#1812）](https://github.com/google/docsy/issues/1812)。

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

<!-- markdownlint-disable no-shortcut-ref-link -->

- [BSv5.2 升级后续](https://github.com/google/docsy/issues/1510)
- [升级到 Bootstrap 5.3（#1528）](https://github.com/google/docsy/issues/1528)
- [[BSv5] 使用 RTLCSS Bootstrap 重新引入 RTL 支持](https://github.com/google/docsy/issues/1442)
- [支持添加主题颜色](https://github.com/google/docsy/issues/1845)

<!-- markdownlint-enable no-shortcut-ref-link -->

[`.td-heading-self-link`]:
  https://github.com/chalin/docsy/blob/849dea0790bbaef5f4f71659824f44045afcd65e/assets/scss/_content.scss#L98
[@jmooring]: https://github.com/jmooring
[@sarahmaddox]: https://github.com/sarahmaddox
[#138]: https://github.com/google/docsy/issues/138
[#1460]: https://github.com/google/docsy/issues/1460
[#1500]: https://github.com/google/docsy/pull/1500
[#1744]: https://github.com/google/docsy/pull/1744
[#1812]: https://github.com/google/docsy/issues/1812
[#1814]: https://github.com/google/docsy/issues/1814
[#1815]: https://github.com/google/docsy/pull/1815
[#1817]: https://github.com/google/docsy/pull/1817
[#1818]: https://github.com/google/docsy/pull/1818
[#1820]: https://github.com/google/docsy/issues/1820
[#1841]: https://github.com/google/docsy/issues/1841
[#1852]: https://github.com/google/docsy/issues/1852
[#2]: https://github.com/google/docsy/issues/2
[blocks/feature]: /zh/docs/content/shortcodes/#blocks-feature
[CL@0.9.0]: /zh/project/about/changelog/#v0.9.0
[函数]: https://gohugo.io/functions/
[钩子]: https://gohugo.io/templates/render-hooks/
[Hugo 0.112.0]: https://github.com/gohugoio/hugo/releases/tag/v0.112.0
[语言参数]: /zh/docs/language/#internationalization-bundles
[Lisa]: https://github.com/LisaFC
[path_base_for_github_subdir]:
  /zh/docs/content/repository-links/#path_base_for_github_subdir-optional
[0.9.0]: https://github.com/google/docsy/releases/tag/v0.9.0
[仓库链接]: /zh/docs/content/repository-links/
[tmpl-func]:
  https://discourse.gohugo.io/t/hugo-v0-112-0-new-template-functions/44512
[v0.8.0...v0.9.0]: https://github.com/google/docsy/compare/v0.8.0...v0.9.0

[^1]: 这里的“可观”以 Docsy 发布的一贯规模为参照。