# 0.13.0 发布报告与升级指南

> Docsy 0.13.0 发布报告与升级指南，涵盖目录活动项跟踪、告警短代码改进、 无障碍增强和分区侧边栏根节点。

---

LLMS index: [llms.txt](/llms.txt)

---

<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-fire text-warning fa-lg"></i> <span>Docsy [0.13.0][]
  包含 2025 年[得票最高][most upvoted]的[功能请求][request of 2025]，以及更多改进。</span>
- <i class="fa-solid fa-check text-success fa-lg"></i>
  <span>本版带来新功能，而且只有[少量破坏性变更](#breaking-changes)。[^explain-report-format]</span>
- <i class="fa-solid fa-robot text-info fa-lg"></i> <span>阅读我们使用 AI
  [升级 Docsy 项目](#upgrade)的[实践经验](#upgrading-and-ai)。</span>

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


[^explain-report-format]: 因此，本文不仅是一份升级指南，也是一份发布报告。

[most upvoted]: #active-toc-entry-tracking
[request of 2025]:
  https://github.com/google/docsy/issues?q=is%3Aissue%20state%3Aclosed%20sort%3Areactions-%2B1-desc%20closed%3A2025-01-01..2025-12-31

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

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

- <i class="fa-solid fa-compass text- px-1"></i>
  [导航与用户体验](#navigation-and-ux)改进，包括 2025 年 **得票最高**
  的[功能请求][request of 2025]：[目录活动项跟踪](#active-toc-entry-tracking)（[#349][]、[#2289][]）；
- <i class="fa-solid fa-code text- px-1"></i>
  重写[告警短代码](#alert-shortcode)，更好地支持 Markdown；
- <i class="fa-solid fa-universal-access text- px-1"></i>
  改进[无障碍能力](#accessibility)，增强颜色对比度和深色模式支持。

## 准备升级？<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> [告警短代码](#alert-shortcode)正文处理方式变化；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [语言菜单](#language-menu-visibility)可见性变化。
- 可以快速浏览：
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 新功能；
  - [其他重要变更](#other-notable-changes)。
- <i class="fa-solid fa-rocket text-primary px-1"></i>
  准备好后，直接阅读[升级到 0.13.0](#upgrading-and-ai)。

## <i class="fa-solid fa-compass text- px-1"></i> 导航与用户体验改进 {#navigation-and-ux}

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 目录活动项跟踪 {#active-toc-entry-tracking}

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

[使用 ScrollSpy 跟踪目录活动项]: /zh/docs/content/navigation/#toc-entry-tracking
[ScrollSpy]: https://getbootstrap.com/docs/5.3/components/scrollspy/
[patched]: /zh/project/implementation/scrollspy-patch/

> [!INFO] 想隐藏目录？
>
> 页面参数
> `notoc`（2016 年起即可使用，[现已补充文档][#2405]）可以隐藏指定页面的目录。详情参阅[目录定制][]。
>
> [#2405]: https://github.com/google/docsy/pull/2405

[目录定制]: /zh/docs/content/navigation/#toc-customization

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 分区侧边栏根节点 {#section-sidebar-root}

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

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

[docs-only]: /zh/docs/content/adding-content/#alternative-site-structure
[分区侧边栏根节点]: /zh/docs/content/navigation/#sidebar-root
[#2364]: https://github.com/google/docsy/pull/2364

### <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 语言菜单可见性 {#language-menu-visibility}

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

| 位置       | 宽视口 | 窄视口 |
| ---------- | :----: | :----: |
| **导航栏** |  可见  |  隐藏  |
| **侧边栏** |  隐藏  |  可见  |

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

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

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

这是一项 <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span>
用户体验变更。可以通过以下方式恢复旧行为：

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

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

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

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

[lang-menu]: /zh/docs/content/navigation/#language-menu
[#2303]: https://github.com/google/docsy/pull/2303

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 移动端导航栏滚动提示 {#mobile-navbar-scroll-indicators}

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

[#2406]: https://github.com/google/docsy/pull/2406

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 告警短代码改进 {#alert-shortcode}

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

因此，告警现在可以：

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

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

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

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

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

[Markdown 调用语法]: https://gohugo.io/content-management/shortcodes/#notation

## <i class="fa-solid fa-universal-access text-info px-1"></i> 无障碍改进 {#accessibility}

- <i class="fa-solid fa-palette fa-lg text-info px-1"></i> 主题整体的
  **颜色对比度**
  得到改善，Docsy 现在会回退到 Bootstrap 的字体与颜色默认值，从而提供更好的开箱即用无障碍合规性。详情见
  [#2285][] 和[站点颜色][]。

- <i class="fa-solid fa-palette text-info px-1"></i> 深色模式的 **颜色对比度** 改进：
  - 修复用户偏好与系统设置不同时的目录项颜色对比度（[#2379][]）；
  - 为使用 Bootstrap 主题变量的项目提供早期实验性支持，允许定制对比度调整（[#2384][]）。详情见[选择具有良好对比度的颜色][]。<span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>

- <i class="fa-solid fa-moon text-info px-1"></i> **[深色模式][]**：
  - <i class="fa-solid fa-bolt text-warning px-1"></i>
    修复[无样式内容闪烁][]（FOUC）（[#2332][]）；
  - <i class="fa-solid fa-search text-info px-1"></i> **Google 搜索**
    结果页支持深色模式（[#2387][]）。<span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>

  > [!SECONDARY] 深色模式速查
  >
  > 如需启用全部[深色模式][]功能（包括实验功能），请在
  > [`_styles_project.scss`][project-style-files]
  > 中加入以下导入。详情见[浅色/深色模式][]。
  >
  > ```scss
  > // Dark mode enhancements
  > @import 'td/color-adjustments-dark';
  > @import 'td/code-dark';
  > @import 'td/gcs-search-dark';
  > ```

[深色模式]: /zh/docs/content/lookandfeel/#lightdark-color-modes
[浅色/深色模式]: /zh/docs/content/lookandfeel/#lightdark-color-modes
[#2001]: https://github.com/google/docsy/issues/2001
[#2035]: https://github.com/google/docsy/issues/2035
[#2285]: https://github.com/google/docsy/issues/2285
[#2289]: https://github.com/google/docsy/issues/2289
[#2328]: https://github.com/google/docsy/issues/2328
[#2332]: https://github.com/google/docsy/issues/2332
[#2379]: https://github.com/google/docsy/pull/2379
[#2384]: https://github.com/google/docsy/pull/2384
[#2387]: https://github.com/google/docsy/pull/2387
[#2394]: https://github.com/google/docsy/pull/2394
[#2395]: https://github.com/google/docsy/pull/2395
[无样式内容闪烁]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content
[选择具有良好对比度的颜色]:
  /zh/docs/content/lookandfeel/#pick-good-color-contrast
[project-style-files]: /zh/docs/content/lookandfeel/#project-style-files
[站点颜色]: /zh/docs/content/lookandfeel/#site-colors

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

- **更好的 NPM 支持**：通过 [NPM 使用 Docsy][] 的项目不再遇到 Optional 与 Peer
  Dependency 问题（[#2115][]）。
- **翻译（i18n）**：新增奥克语 Locale（[#2173][]），并更新简体中文（[#2313][]）与乌克兰语（[#2331][]）[翻译文件][]。
- **新增 `_param`
  短代码**：实验性参数替换短代码，适合生成动态模板内容。详情见 PR [#2371][]。
- **数学与化学公式**：Docsy 改用 Hugo 内置 KaTeX 引擎在构建期渲染，`mhchem`
  扩展也已内置。详情见[使用 KaTeX 支持 LaTeX][diagrams-formulae]（[#2276][]、[#2394][]、[#2395][]）。

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

[#2371]: https://github.com/google/docsy/pull/2371
[#2276]: https://github.com/google/docsy/pull/2276
[NPM 使用 Docsy]:
  /zh/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
[翻译文件]: /zh/docs/language/#internationalization-bundles
[diagrams-formulae]:
  /zh/docs/content/diagrams-and-formulae/#latex-support-with-katex

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

### 前提条件 {#prerequisites}

> <i class="fa-solid fa-triangle-exclamation text-warning px-1"></i> **我们建议** 先阅读 [Docsy
> 0.12.0 升级指南][升级到 Docsy 0.12.0]，因为该版本包含重要破坏性变更。

### 升级流程与 AI 辅助 {#upgrading-and-ai}

> <i class="fa-solid fa-robot text-info px-1"></i> 你是否尝试过用 AI 协助升级 Docsy？它能帮上大忙！

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

[TUF PR #126]:
  https://github.com/theupdateframework/theupdateframework.io/pull/126

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

- **Docsy**：[0.12.0][] → [0.13.0][]<br>其中 **Bootstrap**：5.3.6 → 5.3.8
- **Hugo**：0.147.5 → 0.152.2[^vers-note]
  > [!NB] 请注意 [Hugo 0.152.0 **破坏性变更**][hugo-0.152.0]。
- **Node**：LTS 22 → LTS 24[^vers-note]

[^vers-note]:
    以上是对应 Docsy 版本正式支持的 Node.js 与 Hugo 版本。更高版本可能可以工作，但不在正式支持范围内。

升级后，请审阅[破坏性变更](#breaking-changes)，并全面测试站点。测试清单见[升级到
Docsy 0.12.0][]指南。

> [!WARNING] 不支持 Hugo 0.152.0 与 0.152.1
>
> Hugo 0.152.0 或 0.152.1 与 Docsy 0.13.0 不兼容（[#2347][]）；请使用 Hugo
> 0.152.2 或更高版本。

[#2347]: https://github.com/google/docsy/issues/2347

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

2026 年已经规划了令人期待的增强功能[^2026-enhancements]！

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

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

[^2026-enhancements]: 有更多细节后，我们会在此发布，或更新 [#2404][]。

<!-- 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
[#1436]: https://github.com/google/docsy/issues/1436
[#1841]: https://github.com/google/docsy/issues/1841
[#2404]: https://github.com/google/docsy/issues/2404
[#375]: https://github.com/google/docsy/issues/375

## 参考资料 {#references}

关于本版：

- [0.13.0 **Changelog**][CL@0.13.0] 条目
- [0.13.0 **发布页**][0.13.0]
- [0.13.0 发布准备 **Issue**（#2266）][#2266]

其他参考资料：

- [0.12.0 升级指南][]
- 从 Hugo 0.147.5 升级到 0.152.2 时的注意事项：
  - 配套文章 [Hugo 0.152.0 破坏性变更][hugo-0.152.0]
  - 官方 [Hugo 发布说明](https://github.com/gohugoio/hugo/releases)

[#349]: https://github.com/google/docsy/issues/349
[#941]: https://github.com/google/docsy/pull/941
[#2115]: https://github.com/google/docsy/issues/2115
[#2173]: https://github.com/google/docsy/issues/2173
[#2266]: https://github.com/google/docsy/issues/2266
[#2313]: https://github.com/google/docsy/issues/2313
[#2331]: https://github.com/google/docsy/issues/2331
[0.12.0]: /zh/project/about/changelog/#v0.12.0
[0.13.0]: https://github.com/google/docsy/releases/v0.13.0
[alert]: /zh/docs/content/shortcodes/#alert
[CL@0.13.0]: /zh/project/about/changelog/#v0.13.0
[升级到 Docsy 0.12.0]: /zh/blog/2025/0.12.0/
[0.12.0 升级指南]: /zh/blog/2025/0.12.0/
[hugo-0.152.0]: /zh/blog/2026/hugo-0.152.0+/#0.152.0

> [!NB] **最后更新**：2026-02-07