0.15.0 发布报告与升级指南

发布摘要

• 智能体支持（实验性）：
  • 生成 llms.txt；
  • 为首页、分区和页面内容生成 Markdown 备用输出；
  • 页面存在 Markdown 备用版本时显示“查看 Markdown”页面元数据链接。
• 文档根站点（实验性）：记录将 docs 分区发布到站点根路径的模式，并提供对应样例变体；
• 版本菜单条目：支持标题、分隔线、逐条页面链接行为和基于 Kind 的样式；
• 内容、短代码与国际化：
  • 社区与 Footer 链接；
  • card 短代码渲染；
  • 国际化新增与更新。

准备升级？

• 审阅 BREAKING 变更：
  • 社区与 Footer 链接；
  • 版本菜单条目；
  • 卡片短代码渲染（低风险）。
• 可以快速浏览：
  • 新功能（寻找绿色对勾图标）；
  • 清理与改进机会（寻找对应图标）；
  • 其他重要变更。
• 准备好后，直接阅读升级到 0.15.0。

智能体支持

0.15.0 包含智能体支持的第一阶段实现，提供一组可选择启用的功能，帮助 AI 智能体与自动化工具发现并使用站点内容：

• llms.txt；
• 首页、分区和页面内容的 Markdown 备用输出；
• 存在 Markdown 备用版本时显示 查看 Markdown 页面元数据链接。

如何为站点启用智能体支持及详细配置，见智能体支持。该功能为实验性。

智能体支持功能的分阶段演进见改进 AI 智能体文档消费支持 #2614。

文档根站点

Docsy 对 文档根站点 提供了新的改进支持，即把 docs 分区发布到站点根路径，而不是 /docs/ 下。这适用于以文档为主体、希望 URL 更短的站点，例如使用 /get-started/ 而不是 /docs/get-started/。

文档根站点也可以在站点根路径保留博客、社区等非文档分区。详情见文档根站点，也可以访问本站的文档根样例变体。该功能为实验性。

操作

适用条件：项目使用基于 Front Matter cascade 或 type 变更的旧版纯文档配置。

• 删除旧版纯文档 Cascade 配置；
• 按照文档根站点说明，为 docs 分区改用 Hugo permalinks 配置；
• 运行 hugo --printPathWarnings 检查路径冲突。正确配置后不应存在冲突。

/ 版本菜单条目

Docsy 导航栏的版本菜单现在支持更丰富的条目处理：文字标题、分隔线、逐条页面链接行为，以及基于 Kind 的菜单项样式。配置详情见添加版本下拉菜单。

既有的简单 version 与 url 条目仍然有效。如果项目定制了版本菜单 Partial、CSS 或移动端导航栏布局，这项变更可能具有破坏性：菜单使用了更新后的标记与 class，而且在较小视口中不再隐藏。

操作

适用条件：项目配置 params.versions，并定制版本菜单或导航栏。

• 审阅定位版本菜单下拉框的自定义 CSS；
• 如果维护本地 layouts/_partials/navbar-version-selector.html 或 layouts/_partials/navbar.html 覆盖项，与 v0.15.0 导航栏 Partial进行 Diff；
• 重新检查桌面端和移动端导航栏。

配置与样式详情见版本菜单和添加版本下拉菜单。

/ 社区与 Footer 链接

新增行为与修复：

• Footer 链接支持 rel 属性，见添加社区页面（#2576）；
• 社区与 Footer 链接现在只为外部链接打开新浏览器目标，修复 #2133（#2576）；
• 站点内部的社区与 Footer 链接能在任意永久链接方案下正确解析（#2580）。

破坏性变更：

• 在多语言站点中，链接路径现在按站点相对路径解释（#2580）。

操作

适用条件：多语言站点在社区或 Footer 链接中配置站点内部路径。

• 检查 params.links.user 与 params.links.developer 路径值，逐条判断目标应当是默认语言，还是当前站点（Locale）相对路径；

• 如果路径应相对于当前站点，保持不变；

• 如果路径应指向默认语言站点（即位于默认语言前缀下），请添加该前缀，例如用 /en/community/ 替代 /community/。

  说明

  如果默认语言发布在站点根路径，例如设置 defaultContentLanguageInSubdir: false，或使用 Sites Matrix/默认语言回退，那么 /community/ 可能已经指向默认语言。只有带前缀 URL 确实存在，而且是期望的规范目标时，才添加语言前缀。

• 在每种语言中重新检查生成的社区和 Footer 链接，确认目标站点正确。

/ 卡片短代码渲染

card 短代码一直支持在参数中使用 Markdown。现在，这些参数会在包含 card 的页面上下文中渲染，也就是说，参数值中的 Markdown 会在当前页面上下文解析，从而支持：

• 在 card 参数 Markdown 中使用相对链接路径；
• 在页面上下文中触发 Markdown 渲染钩子。

相对链接路径对多语言站点非常重要；在页面上下文中执行渲染钩子，也能提供更灵活的行为。

例如，下面的 card Footer 参数使用相对路径引用页面包图片资源：

{{< card
  header="**Imagine**" ...
  footer="![John's signature](card-pane/john-lennon-signature.png)"
>}}
...
{{< /card >}}

完整示例见card 短代码。

操作

适用条件：项目使用 card.html 短代码或维护自定义覆盖项。

• 确认卡片渲染仍符合预期；
• 如果希望使用新能力，更新站点的 card 覆盖项。

其他重要变更

国际化

变更摘要：

• 新增或更新以下 Locale 的翻译文件：
  • 阿塞拜疆语：新增（#2082、#2604）；
  • 罗马尼亚语：新增（#2583、#2603）；
  • 德语：增加告警标签翻译（#2591）。
• 为新增的“查看 Markdown”标签补充基础翻译（#2602）。

升级到 0.15.0

使用 AI 升级？0.15.0 附带实验性的机器可读升级清单，其中包含升级检测规则、适用条件、基本检查和逐项参考资料。可以把本发布报告与清单一起作为 AI 助手的上下文。

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

• Docsy：0.14.3 → 0.15.0
• Hugo：0.155.3 → 0.157.0
• Node：LTS 24（不变）

接下来是什么？

下一版暂定工作项见 0.16.0 发布准备（#2615）。

参考资料

关于本版：

• 0.15.0 Changelog 条目
• 0.15.0 发布页
• 0.15.0 发布准备 Issue（#2501）

• ←上一页
• 下一页→