# 0.15.0 发布报告与升级指南

> Docsy 0.15.0 发布报告与升级指南，涵盖智能体支持、文档根站点、版本菜单、 社区与 Footer 链接，以及卡片短代码渲染。

---

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

---

<!-- markdownlint-disable no-space-in-emphasis -->

<div class="td-card card border me-4">
<div class="card-header">
      亮点
    </div>
<div class="card-body">
    <p class="card-text">
        

- <i class="fa-solid fa-robot text-info fa-lg"></i>
  <span>**[智能体支持](#agent-support)**：`llms.txt`、Markdown 页面输出，以及“查看 Markdown”页面元数据链接</span>
- <i class="fa-solid fa-diagram-project text-success fa-lg"></i>
  <span>**[文档根站点](#doc-rooted-sites)**：改进把文档发布到站点根路径的支持</span>
- <i class="fa-solid fa-code-branch text-primary fa-lg"></i>
  <span>**[版本菜单](#version-menu)**：更丰富的条目与更新后的导航栏渲染</span>

</p>
      </div>
  </div>


## 发布摘要 {#release-summary}

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

## 准备升级？<a id="breaking-changes"></a> {#ready-to-upgrade}

- 审阅 <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span> 变更：
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [社区与 Footer 链接](#community-footer-links)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [版本菜单条目](#version-menu)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [卡片短代码渲染](#card-shortcode)（低风险）。
- 可以快速浏览：
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 新功能（寻找绿色对勾图标）；
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 清理与改进机会（寻找对应图标）；
  - [其他重要变更](#other-notable-changes)。
- <i class="fa-solid fa-rocket text-primary px-1"></i>
  准备好后，直接阅读[升级到 0.15.0](#upgrade)。

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 智能体支持 {#agent-support}

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

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

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

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

[#2614]: https://github.com/google/docsy/issues/2614
[智能体支持]: /zh/docs/content/agent-support/

## <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 文档根站点 {#doc-rooted-sites}

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

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

### 操作 {#doc-rooted-sites-actions}

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

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

[old-docs-only-config]:
  https://web.archive.org/web/20260216125700/https://www.docsy.dev/docs/content/adding-content/#alternative-site-structure

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 版本菜单条目 {#version-menu}

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

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

### 操作 {#version-menu-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：项目配置
`params.versions`，并定制版本菜单或导航栏。

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

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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 社区与 Footer 链接 {#community-footer-links}

新增行为与修复：

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

[永久链接]: https://gohugo.io/configuration/permalinks/

破坏性变更：

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

### 操作 {#community-footer-links-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i>
**适用条件**：多语言站点在社区或 Footer 链接中配置站点内部路径。

- 检查 `params.links.user` 与 `params.links.developer`
  路径值，逐条判断目标应当是默认语言，还是当前站点（Locale）相对路径；
- 如果路径应相对于当前站点，保持不变；
- 如果路径应指向默认语言站点（即位于默认语言前缀下），请添加该前缀，例如用
  `/en/community/` 替代 `/community/`。

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

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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 卡片短代码渲染 {#card-shortcode}

> [!NOTE] **摘要：破坏风险较低**
>
> 从技术上说，`card` 参数现在使用 [`.Page.RenderString`][] 而不是
> [markdownify][]
> 渲染。我们预计这不会造成破坏；如果确实遇到问题，请[提交 Issue][new-issue]。

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

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

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

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

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

完整示例见[card 短代码][]。

### 操作 {#card-shortcode-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：项目使用 [card.html][]
短代码或维护自定义覆盖项。

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

## 其他重要变更 {#other-notable-changes}

### <i class="fa-solid fa-globe text- px-1"></i> 国际化 {#internationalization}

变更摘要：

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

## <i class="fa-solid fa-rocket text-primary px-1"></i> 升级到 0.15.0 {#upgrade}

> <i class="fa-solid fa-robot text-info px-1"></i>
> **使用 AI 升级**？0.15.0 附带实验性的机器可读[升级清单](/upgrades/0.15.0.yaml)，其中包含升级检测规则、适用条件、基本检查和逐项参考资料。可以把本发布报告与清单一起作为 AI 助手的上下文。

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

- **Docsy**：[0.14.3][] → [0.15.0][]
- **Hugo**：[0.155.3][] → [0.157.0][]
- **Node**：LTS 24（不变）

[^vers-note]:
    与 `docsy.dev` 声明的 `params.hugoMinVersion` 和 `hugo-extended`
    一致。更高版本的 Hugo 或 Node 可能可以工作，但不在正式支持范围内。

> [!NOTE]
>
> **需要回滚**？按照[0.12.0 升级流程][升级到 Docsy 0.12.0]反向操作，把 Docsy 重新锁定到
> [0.14.3][]，并使用 Hugo 0.155.3。

<section class="td-checkbox-list-wrapper">

### <i class="fa-solid fa-square-check text-primary px-1"></i> 基本检查 {#sanity-checks}

- [ ] 在本地 **构建站点**：
  - 如果站点是[文档根站点](#doc-rooted-sites)，运行 `hugo` 时添加
    `--printPathWarnings`；
- [ ] 多语言站点[检查社区与 Footer 链接](#community-footer-links)；
- [ ] 如果使用版本菜单，在桌面端与移动端[检查版本菜单](#version-menu-actions)；
- [ ] [检查使用 `card` 短代码的页面](#card-shortcode-actions)；
- [ ] 如果[启用了智能体支持](#agent-support)，检查生成的 `*.md` 和 `/llms.txt`
      页面。

</section>

## 接下来是什么？ {#whats-next}

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

<!-- prettier-ignore -->
> [!INFO]- 你的意见很重要！
>
> - <i class="fa-solid fa-thumbs-up text-success px-1"></i> 如果希望某项功能或修复进入后续版本，请为相关 Issue 或 PR **点赞投票**；
>
> - <i class="fa-solid fa-star text-warning px-1"></i> 如果 Docsy 对你有帮助，请考虑为[仓库加星][star-the-repo]，表达支持。
{._list-unstyled}

[star-the-repo]: https://github.com/google/docsy

## 参考资料 {#references}

关于本版：

- [0.15.0][CL@0.15.0] Changelog 条目
- [0.15.0][] 发布页
- [0.15.0 发布准备 Issue（#2501）][#2501]

<!-- prettier-ignore-start -->
[`.Page.RenderString`]: https://gohugo.io/methods/page/renderstring/
[#2082]: https://github.com/google/docsy/pull/2082
[#2133]: https://github.com/google/docsy/issues/2133
[#2501]: https://github.com/google/docsy/issues/2501
[#2576]: https://github.com/google/docsy/pull/2576
[#2580]: https://github.com/google/docsy/pull/2580
[#2583]: https://github.com/google/docsy/pull/2583
[#2591]: https://github.com/google/docsy/pull/2591
[#2602]: https://github.com/google/docsy/pull/2602
[#2603]: https://github.com/google/docsy/pull/2603
[#2604]: https://github.com/google/docsy/pull/2604
[#2615]: https://github.com/google/docsy/issues/2615
[0.14.3]: https://github.com/google/docsy/releases/v0.14.3
[0.15.0]: https://github.com/google/docsy/releases/v0.15.0
[0.155.3]: https://github.com/gohugoio/hugo/releases/tag/v0.155.3
[0.157.0]: https://github.com/gohugoio/hugo/releases/tag/v0.157.0
[添加社区页面]: /zh/docs/content/adding-content/#adding-a-community-page
[添加版本下拉菜单]: /zh/docs/content/versioning/#adding-a-version-drop-down-menu
[card 短代码]: /zh/docs/content/shortcodes/#shortcode-card-textual-content
[card.html]: https://github.com/google/docsy/blob/v0.15.0/layouts/_shortcodes/card.html
[CL@0.15.0]: /zh/project/about/changelog/#v0.15.0
[文档根样例]: https://doc-rooted--docsydocs.netlify.app
[文档根站点]: /zh/docs/content/adding-content/#doc-rooted-sites
[实验性]: /zh/project/about/changelog/#experimental
[markdownify]: https://gohugo.io/functions/transform/markdownify/
[多语言站点]: /zh/docs/language/
[new-issue]: https://github.com/google/docsy/issues/new/choose
[升级到 Docsy 0.12.0]: /zh/blog/2025/0.12.0/
[v0.15.0 导航栏 Partial]: https://github.com/google/docsy/tree/v0.15.0/layouts/_partials
[版本菜单]: /zh/docs/content/navigation/#version-menu
<!-- prettier-ignore-end -->