# 0.14.0 发布报告与升级指南

> Docsy 0.14.0 发布报告与升级指南，涵盖 Markdown 告警语法、导航栏样式改进、 标题别名与页内目标，以及项目与内部 SCSS 文件的进一步分离。

---

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

---

> [!INFO] 0.14.1 至 0.14.3 补丁更新
>
> 这些补丁版本的关键修复见 [0.14.1][CL@0.14.1]、[0.14.2][CL@0.14.2] 与
> [0.14.3][CL@0.14.3]。0.14.2 的其他变化见[补丁更新 0.14.2](#0.14.2)。如果现在升级，请按照本指南操作，并在文中提到 0.14.0 的地方使用 0.14.3。

<style>
  li > div.alert-nb { margin: 0.5rem 0 !important;}
</style>

<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-palette text-success fa-lg"></i>
  <span>[**样式与定制**](#styles-customization)：改进导航栏，重新组织 SCSS 文件</span>
- <i class="fa-solid fa-book text-info fa-lg"></i> <span>**内容与本地化**：新增 Markdown
  [告警语法](#alerts)并改进[国际化](#other-notable-changes)</span>
- <i class="fa-solid fa-triangle-exclamation text-warning fa-lg"></i>
  <span>**[要求 Hugo 0.155.0](#hugo)**，以及 0.153+ 的破坏性与重要变化</span>

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


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

- **[样式与定制](#styles-customization)**：
  - [导航栏改进](#navbar)，包括可配置浅色/深色主题与可调整高度；
  - [标题别名与页内目标](#heading-aliases)；
  - [重新组织内部 SCSS 文件](#improved-scss-soc)。
    > [!NB] :warning: 如果你[定制 **Swagger UI**][]，这会影响你的项目！
- **内容、短代码与国际化**：
  - 新增 Markdown [告警语法](#alerts)；
  - [`blocks/cover`](#blocks-cover) 短代码变更；
  - 新增用于 Netlify 构建信息的[短代码](#shortcodes)；
  - [国际化](#other-notable-changes)更新。
- 要求 **[Hugo 0.155.0 或更高版本](#hugo)**；同时讨论破坏性变更与
  [sites.matrix][] 等新功能；
- **[公开功能与内部功能](#clarified-public-vs-internal-theme-features)**：新增定义，明确定制表面、私有/内部功能和支持边界。

[定制 **Swagger UI**]: #swagger-scss
[sites.matrix]: https://gohugo.io/quick-reference/glossary/#sites-matrix

## 准备升级？<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> [样式与定制](#styles-customization)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [标题别名与页内目标](#heading-aliases)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [blocks/cover 短代码](#blocks-cover)正文处理；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Hugo 0.155.0 要求与 0.153+ 破坏性变更](#hugo)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i>（仅样式）[Docsy 0.14.2 代码样式更新](#0.14.2)，适配浅色/深色模式。
- 可以快速浏览：
  - <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.14.0](#upgrade)。

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Markdown 告警语法 {#alerts}

Docsy 0.14.0 支持 Hugo 的 Markdown 告警语法：

```markdown
> [!NOTE] :star: Markdown alert syntax
>
> This syntax is more author, tooling, and AI friendly.
```

渲染结果如下：

> [!NOTE] :star: Markdown 告警语法
>
> 这种语法对作者、工具与 AI 更友好。

我们仍然支持 [alert
短代码][]，但建议新内容采用 Markdown 告警。新语法与定制方式见[告警][]。

### 操作（可选） {#alerts-actions}

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **适用条件**：项目使用 `alert`
短代码。可以考虑迁移到 Markdown 告警，以保持一致，并改善创作与工具支持：

- 新内容使用 Markdown 告警语法；
- 输出等价时，把既有 `alert` 短代码替换为 Markdown 语法；
- 依赖短代码特有行为时，继续保留 `alert`。

> [!TIP]
>
> [docsy-alerts-to-md/convert.pl][] 等脚本可以帮助完成转换。

[alert 短代码]: /zh/docs/content/shortcodes/#alert
[告警]: /zh/docs/content/adding-content/#alerts
[docsy-alerts-to-md/convert.pl]:
  https://github.com/open-telemetry/opentelemetry.io/blob/main/scripts/docsy-alerts-to-md/convert.pl

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 样式与定制 {#styles-customization}

本节介绍导航栏的破坏性变更（以 :warning: 标记）与新功能、[内部][]
SCSS 文件重组，以及它对 Swagger UI 定制的影响。

[内部]: /zh/project/about/changelog/#private

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 导航栏样式改进 {#navbar}

**亮点**：

- 导航栏可以在站点级或逐页配置为 **浅色或深色** 主题，否则默认跟随站点主题；
- 只需一个 SCSS 变量即可调整导航栏 **高度**；
- **新增变量与 class**，让导航栏外观更易定制；
- 改进导航栏覆盖在首屏图片上时的样式与半透明行为；
- **不再意外覆盖 SCSS 文件**！内部 SCSS 现在位于私有 `td/` 子目录。

在 0.14.0 之前，导航栏始终采用深色主题和主色背景。现在，导航栏的[浅色/深色主题][]可以在
**站点级** 和 **逐页**
配置，缺省时跟随站点主题。默认导航栏样式与站点基础样式一致，使整体外观协调。[^navbar-bg-color]

导航栏 **高度与样式**
可通过以下变量调整（<span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>）：

<!-- prettier-ignore -->
- SCSS 变量：
  - `$td-navbar-min-height`
  - `$td-navbar__main-min-height-mobile`
- <details><summary>CSS 变量</summary>

  - `--td-navbar-bg-color`
  - `--td-navbar-backdrop-filter`
  - `--td-navbar-border-bottom`
  - `--bs-bg-opacity`，与 `--td-navbar-bg-color` 一起控制背景透明度
  - `--bs-link-underline-opacity`，控制导航链接下划线

  </details>

默认[导航栏][]外观和[自定义导航栏][]另有详细说明。

[^navbar-bg-color]: 0.14.0 之前，导航栏背景使用主色。

#### 操作：必需与可选 {#navbar-actions}

项目可能需要在以下方面更新：

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

  <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>
  **导航栏浅色/深色主题**：始终使用深色导航栏是 Docsy 早期限制，并不适合所有站点。现在可以选择最符合项目整体设计的主题。
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i>
    如果设计不要求深色导航栏，可以删除过去仅为强制深色而添加的覆盖项；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 如果设计确实要求深色导航栏，把
    `params.ui.navbar_theme` 设为
    `dark`，恢复旧行为（见[详情][navbar-lightdark-theme]）。

- <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i>
  **导航栏覆盖首屏**：适用于定位导航栏首屏半透明 class 的项目。
  - 审阅并简化样式（见[导航栏首屏图片半透明][]）；
  - 用 `.td-navbar-transparent`（与 `.td-navbar-cover` 配合）替代
    `.navbar-bg-on-scroll` 与 `.navbar-bg-onscroll--fade`。

- <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i>
  **高度与变量**：适用于自定义导航栏高度或样式的项目。使用新增变量与样式审阅并简化定制，见[自定义导航栏][]。

- **导航栏 Partial 覆盖项**：适用于覆盖导航栏 Partial 的项目。请审阅
  [`_nav.html`][] 的变更。

  <details>
  <summary class="h6 text-primary"><span class="fas fa-file-alt"></span> <code>layouts/_partials/navbar.html</code> 编辑摘要</summary>

  <table class="table-bordered">
    <thead>
      <tr>
        <th class="text-center">变更前</th>
        <th class="text-center border-start">变更后</th>
      </tr>
    </thead>
    <tbody>
    <tr><th class="text-center" colspan="2" scope="colgroup">首屏半透明</th></tr>
    <tr><td>
      <ul>
        <li><code>&lt;nav&gt;</code> 只有 <code>td-navbar-cover</code></li>
        <li>项目使用 <code>.navbar-bg-on-scroll</code>、<code>.navbar-bg-onscroll--fade</code></li>
      </ul>
    </td><td class="border-start">
      <ul>
        <li><code>&lt;nav&gt;</code> 同时获得 <code>td-navbar-cover</code> 与 <code>td-navbar-transparent</code></li>
        <li>删除旧 class</li>
      </ul>
    </td></tr>
    <tr><th class="text-center" colspan="2" scope="colgroup">浅色/深色主题</th></tr>
    <tr><td>
      <ul>
        <li><code>&lt;nav&gt;</code> 始终设置 <code>data-bs-theme="dark"</code></li>
      </ul>
    </td><td class="border-start">
      <ul>
        <li>仅当 <code>params.ui.navbar_theme</code> 为 <code>"dark"</code> 时设置 <code>data-bs-theme="dark"</code></li>
        <li>否则跟随站点主题</li>
      </ul>
    </td></tr>
    </tbody>
  </table>

  详情见本“需要操作”章节前几项。

  </details>

[`_nav.html`]:
  https://github.com/google/docsy/blob/main/theme/layouts/_partials/navbar.html
[自定义导航栏]: /zh/docs/content/lookandfeel/#navbar-customization
[浅色/深色主题]: /zh/docs/content/lookandfeel/#navbar-lightdark-theme
[导航栏]: /zh/docs/content/lookandfeel/#navbar
[navbar-lightdark-theme]: /zh/docs/content/lookandfeel/#navbar-lightdark-theme
[导航栏首屏图片半透明]: /zh/docs/content/lookandfeel/#customize-over-cover

### <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 标题别名与页内目标 {#heading-aliases}

标题别名可以让旧[片段][]链接继续工作。0.14.0 使用纯 CSS `scroll-padding-top`
修复滚动行为，因此标题别名目标与页内目标现在会滚动到正确位置。详情见[标题别名与页内目标][heading-aliases+]及 PR
[#2505][]。

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

#### 操作：必需与可选 {#heading-aliases-actions}

- <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点使用 `td-offset-anchor`，例如覆盖
  `blocks/lead.html`、`blocks/section.html` 或 `layouts/community/list.html`。

  把 `td-offset-anchor` 重命名为
  `td-anchor-no-extra-offset`，见[实现说明][heading-aliases-impl-notes]。

- **滚动行为**：适用于希望确保既有标题别名与页内目标正确滚动的项目。
  - 如果尚未采用，请把标题别名与页内目标改为
    [`<a id="..."></a>`][heading-aliases+]；
  - 尤其应把 `<span>` 等非 Anchor 目标替换为
    `<a id="..."></a>`，提高滚动可靠性；
  - 把 `<a name="...">` 等旧目标改为基于 `id` 的目标。

[片段]: https://gohugo.io/quick-reference/glossary/#fragment
[heading-aliases+]: /zh/docs/content/navigation/#heading-aliases
[heading-aliases-impl-notes]:
  /zh/docs/content/navigation/#heading-aliases-implementation-notes

### 更好地区分项目与内部 SCSS 文件 {#improved-scss-soc}

Docsy 0.14.0 把全部[内部][] SCSS 文件从 `assets/scss/` 移入 `assets/scss/td/`
子目录。这项变更清楚地区分[项目样式文件][]与主题内部文件，帮助项目避免意外覆盖 Docsy 内部 SCSS。关于如何定制 Docsy 外观，参阅[项目样式][]，其中涵盖：

- 支持项目专属 SCSS 定制的[项目样式文件][]；
- 项目偶尔需要大幅偏离 Docsy 基础样式时使用的[高级样式定制][]。

#### 操作：必需与可选 {#scss-actions}

**适用条件**：项目在 `assets/scss/`
中存在下列文件，因为这意味着项目覆盖了 Docsy 内部 SCSS。[^scss-action-note]

[^scss-action-note]:
    除
    [Swagger UI 样式定制](#swagger-scss)外，这不是破坏性变更，因为只涉及内部文件。

<details>
<summary>
<span class="text-primary h6">
<span class="fas fa-file-alt"></span>
移入 <code>td/</code> 子目录的内部 <code>assets/scss/</code> 文件列表
</span>
</summary>

```text
assets/scss/
├── _alerts.scss
├── _blog.scss
├── _boxes.scss
├── _breadcrumb.scss
├── _code.scss
├── _colors.scss
├── _content.scss
├── _drawio.scss
├── _main-container.scss
├── _nav.scss
├── _navbar-mobile-scroll.scss
├── _pageinfo.scss
├── _search.scss
├── _sidebar-toc.scss
├── _sidebar-tree.scss
├── _swagger.scss
├── _table.scss
├── _taxonomy.scss
├── _variables_forward.scss
├── _variables.scss
├── blocks/_blocks.scss
├── blocks/_cover.scss
├── section-index.scss
├── shortcodes.scss
├── shortcodes/cards-pane.scss
├── shortcodes/tabbed-pane.scss
├── support/_bootstrap_vers_test.scss
├── support/_mixins.scss
├── support/_rtl.scss
└── support/_utilities.scss
```

</details>

例如，要继续使用 `assets/scss/_table.scss` 中的定制，请在 `_styles_project.scss`
中加入：

```scss
@import 'table';
```

也可以把样式直接复制到 `_styles_project.scss`。

#### <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Swagger UI 样式定制 {#swagger-scss}

**适用条件**：项目定制 Swagger UI 样式。

0.14.0 之前，用户指南错误地建议覆盖 `_swagger.scss` 来定制 [Swagger UI][]
样式。[内部][]
SCSS 文件不应被覆盖，指南现已纠正。由于这一覆盖方式曾写入文档，移动该文件被视为[破坏性变更][]，因此在这里特别说明。

如果项目有 Swagger
UI 样式定制，请按照上一节[需要操作](#scss-actions)中的步骤处理。

[破坏性变更]: /zh/project/about/changelog/#breaking-change
[Swagger UI]: /zh/docs/content/shortcodes/#swaggerui

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> `blocks/cover` 短代码变更 {#blocks-cover}

[blocks/cover][] 有两项变化，其中第一项具有破坏性：

1. 短代码现在直接使用
   `.Inner`，依赖 Hugo 原生 Markdown 内容处理，而不再检查文件扩展名（[#939][]、[#2480][]）；
2. 新增 `td-below-navbar` 辅助 class，可以让首屏在桌面端位于固定导航栏
   **下方**，而不是其后。

### 操作：必需与可选 {#blocks-cover-actions}

- <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：在 `.html` 内容文件中使用
  `blocks/cover`，且正文包含 Markdown。

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

- <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **建议多数项目采用**。[^below-navbar-default] 如果希望
  `blocks/cover` 位于导航栏下方而不是其后，请在调用中加入 `td-below-navbar`
  辅助 class，例如 `height="auto td-below-navbar"`。详见[导航栏下方高度调整][]。

  [^below-navbar-default]:
      我们预计 `td-below-navbar`
      对多数项目都是更合适的设计，未来版本可能将其设为默认值。

[导航栏下方高度调整]: /zh/docs/content/shortcodes/#td-below-navbar
[blocks/cover]: /zh/docs/content/shortcodes/#blocks-cover
[Markdown 调用语法]: https://gohugo.io/content-management/shortcodes/#notation

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Hugo 要求与破坏性变更 {#hugo}

Docsy 0.14.0 [正式支持][] **Hugo 0.155.0 或更高版本**，高于 [Docsy
0.13.0][升级到 Docsy 0.13.0]的 0.152.2。Hugo
0.153+ 引入可能影响站点的破坏性变更，也增加 [sites.matrix][] 提供的
**多维内容模型** 等重要新功能。

完整细节见配套 [Hugo 0.152.0–0.155.x 升级指南][hugo-0.152.0+]。从 Hugo
0.153+ 开始的全面问题与注意事项见 [Hugo
0.153+ 破坏性变更与问题（#2431）][#2431]。

## <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> 补丁更新 0.14.2 {#0.14.2}

Docsy 0.14.2 包含以下变化：

- 对使用 `td/code-dark` 的站点，默认代码样式从 `tango`/`onedark` 改为
  `friendly`/`native`（[#2548][]）；
- <i class="fa-regular fa-square-check fa-lg text-success px-1"></i>
  选择控制台代码块和复制代码时，现在只包含命令，不含输出（[#2548][]）。详情见[选择控制台代码块内容][]；
- 搜索表单新增 `name` 属性，改进语义与自动填充行为（[#2549][]）。

### 操作：必需与可选 {#0.14.2-actions}

- <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：使用 `td/code-dark`，而且希望恢复
  `tango`/`onedark` 样式。请按照[浅色/深色代码样式及其他配置][]操作；
- 验证控制台示例的复制代码行为——只复制命令——是否符合预期。恢复旧行为见[选择控制台代码块内容][]。

[浅色/深色代码样式及其他配置]:
  /zh/docs/content/lookandfeel/#lightdark-code-styles
[选择控制台代码块内容]:
  /zh/docs/content/lookandfeel/#selecting-console-block-content

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

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

变更摘要：

- 主题 i18n 从 TOML 转换为 YAML；删除冗余 `other`
  形式，改用默认单数/复数语法（[#2447][]）；
- 新增 Locale：希伯来语；
- 为多个 Locale 添加告警类型标签（[#2390][]）。

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i>
**操作（可选）**：适用于包含 i18n 文件的项目。可以借机清理并减少[技术债务][]：

- Docsy 的新增或更新已经覆盖的条目，可以从项目文件中删除；
- 删除冗余 `other` 形式，简化 i18n 文件；无论是否转换为 YAML 都可以这样做。

### 样式改进与修复 {#style-improvements-and-fixes}

Docsy 0.14.0 包含以下样式改进与修复：

- 导航栏颜色对比度修复（[#2413][]、[#2477][]）；
- `<details>` 外边距修复；
- 目录中的 h1 条目略微加粗，增强视觉区分；
- Google 搜索 Modal 支持深色模式（[#2524][]）；
- RTL：代码块与可折叠导航图标（[#2533][]）。

[实验性][experimental]额外样式：

- CTA 按钮组：使用 `td-cta-buttons` class；
- 导航栏链接活动与悬停状态装饰；
- 嵌套列表最后一个子项的外边距修复；
- 无左侧边栏布局：使用 `td-no-left-sidebar` class；
- 首页导航栏辅助 class `td-navbar-links-all-active`。

详情见[额外样式][]。

[额外样式]: /zh/docs/content/lookandfeel/#extra-styles

### 短代码 {#shortcodes}

- 新增[实验性][experimental] `td/site-build-info/netlify`
  短代码，用于显示 Netlify 构建信息。见[示例](/zh/project/#site-build-information)。

### 明确公开功能与内部主题功能 {#clarified-public-vs-internal-theme-features}

Docsy
0.14.0 新增[定义](/zh/project/about/changelog/#definitions)，明确公开定制表面、内部/私有功能与支持边界，使读者知道哪些内容得到支持、哪些变更需要操作：

- [公开定制表面](/zh/project/about/changelog/#public)
- [私有/内部功能](/zh/project/about/changelog/#private)
- [实验性功能][experimental]
- [破坏性变更](/zh/project/about/changelog/#breaking-change)
- [正式支持边界](/zh/project/about/changelog/#official-support)

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

> [!NB] 如果尚未升级，请先[升级到 Docsy 0.13.0][]。

### 升级步骤 {#upgrade-steps}

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

- **Docsy**：[0.13.0][] → [0.14.3][]
- **Hugo**：0.152.2 → 0.155.0 或更高版本，见 [Hugo
  0.152.0–0.155.x 升级指南][hugo-0.152.0+]
- **Node**：LTS 24（不变）

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

<details>
<summary class="h4 text-primary"><span class="fa-regular fa-square-check"></span> 检查</summary>

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

### 基本检查 {#sanity-checks}

升级后，请检查：

- [ ] **构建输出**：站点构建没有错误、警告和弃用通知；
- [ ] **[样式与定制](#styles-customization)**：站点外观符合预期，并执行下方[界面与体验抽查](#ui-ux-spot-checks)；
- [ ] **别名**：默认语言重定向正确，页面别名指向正确语言版本。Hugo
      0.153+ 的别名相关变化见 [Hugo 0.152.0–0.155.x 升级指南][hugo-0.152.0+]。

同时审阅 0.12.0 的[测试清单][]。

### 交叉检查 {#cross-checks}

确认所有[破坏性变更](#breaking-changes)均已处理。下面汇总每节的必需与可选操作。

#### 必需操作（如适用） {#required-actions}

- [ ] [导航栏必需操作](#navbar-actions)
- [ ] [`blocks/cover` 必需操作](#blocks-cover-actions)
- [ ] [内部 SCSS 必需操作](#scss-actions)，包括 [Swagger UI](#swagger-scss)
- [ ] [标题别名与页内目标必需操作](#heading-aliases-actions)

#### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 清理与站点改进（可选） {#cleanup-opportunities}

如果项目覆盖 Docsy 样式——导航栏、Block、目录等——请对照本版变化审阅覆盖项。这通常可以删除自定义 CSS/SCSS，减少[技术债务][]。

- [ ] 切换到 [Markdown 告警语法](#alerts-actions)
- [ ] 审阅[导航栏主题与样式](#navbar-actions)，删除只为强制深色主题而添加的覆盖项
- [ ] 调整 `blocks/cover` 相对于导航栏的[位置](#blocks-cover-actions)
- [ ] 删除冗余 [i18n 条目](#internationalization)

#### 界面与体验抽查（可选） {#ui-ux-spot-checks}

以下快速检查对应 0.14.0 的样式与行为变更：

- [ ] 导航栏主题、高度与首屏半透明效果符合预期；
- [ ] 片段链接和页内目标落在固定导航下方（见[标题别名与页内目标](#heading-aliases)）；
- [ ] 内容页 `<details>` 间距正确；
- [ ] 右侧栏目录 h1 粗细与对比度正确；
- [ ] 使用 `td/code-dark` 时，浅色与深色模式中的代码块样式符合预期；
- [ ] 控制台复制代码按预期只复制命令，不含输出；
- [ ] 启用实验性额外样式时，检查导航链接装饰与嵌套列表间距。

#### 高级审阅 {#advanced-overrides}

**适用条件**：项目覆盖 Docsy 模板、短代码、资源或 i18n 文件。

审阅以下更新文件，并按需移植变更：

- [ ] [assets/js/base.js][]
- [ ] [assets/scss 文件](#scss-actions)
- [ ] [i18n 文件](#internationalization)
- [ ] [layouts/\_markup/render-blockquote-alert.html][render-blockquote-alert.html]
- [ ] [layouts/\_partials/navbar.html](#navbar-actions)
- [ ] [layouts/\_partials/sidebar-tree.html][sidebar-tree.html]
- [ ] [layouts/\_partials/sidebar.html][sidebar.html]
- [ ] [layouts/\_shortcodes/blocks/cover.html][blocks/cover.html]
- [ ] [layouts/\_shortcodes/blocks/lead.html][blocks/lead.html]
- [ ] [layouts/\_shortcodes/blocks/section.html][blocks/section.html]
- [ ] [layouts/\_shortcodes/pageinfo.html][pageinfo.html]
- [ ] [layouts/\_shortcodes/td/site-build-info/netlify.md][site-build-info-netlify.md]
- [ ] [layouts/blog/baseof.html][blog/baseof.html]
- [ ] [layouts/community/list.html][community/list.html]
- [ ] [layouts/docs/baseof.html][docs/baseof.html]
- [ ] [layouts/swagger/baseof.html][swagger/baseof.html]

[assets/js/base.js]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/assets/js/base.js?plain=1>
[render-blockquote-alert.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_markup/render-blockquote-alert.html?plain=1>
[sidebar.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_partials/sidebar.html?plain=1>
[sidebar-tree.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_partials/sidebar-tree.html?plain=1>
[blocks/cover.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_shortcodes/blocks/cover.html?plain=1>
[blocks/lead.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_shortcodes/blocks/lead.html?plain=1>
[blocks/section.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_shortcodes/blocks/section.html?plain=1>
[pageinfo.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_shortcodes/pageinfo.html?plain=1>
[site-build-info-netlify.md]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/_shortcodes/td/site-build-info/netlify.md?plain=1>
[blog/baseof.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/blog/baseof.html?plain=1>
[community/list.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/community/list.html?plain=1>
[docs/baseof.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/docs/baseof.html?plain=1>
[swagger/baseof.html]:
  <https://github.com/pgsty/oink.pgsty.com/blob/main/theme/layouts/swagger/baseof.html?plain=1>

</section>
</details>

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

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

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

## 目标与反馈 {#goals-and-feedback}

本文旨在帮助 Docsy 项目维护者升级到 0.14.0，重点提供可执行操作。欢迎提交
[Issue][] 或发起[讨论][]，告诉我们还可以如何改进。

[Issue]: https://github.com/google/docsy/issues
[讨论]: https://github.com/google/docsy/discussions

## 参考资料 {#references}

关于本版：

- [0.14.0][CL@0.14.0] 至 [0.14.3][CL@0.14.3] 的 Changelog 条目
- [0.14.3][]、[0.14.2][]、[0.14.1][] 与 [0.14.0][] 发布页
- [0.14.0 发布准备 **Issue**（#2404）][#2404]

其他参考资料：

- 配套 [Hugo 0.152.0–0.155.x 升级指南][hugo-0.152.0+]
- [0.13.0 升级指南](/zh/blog/2025/0.13.0/)
- [Hugo 发布说明](https://github.com/gohugoio/hugo/releases)

[#2390]: https://github.com/google/docsy/issues/2390
[#2413]: https://github.com/google/docsy/issues/2413
[#2431]: https://github.com/google/docsy/issues/2431
[#2447]: https://github.com/google/docsy/pull/2447
[#2477]: https://github.com/google/docsy/pull/2477
[#2480]: https://github.com/google/docsy/pull/2480
[#2501]: https://github.com/google/docsy/issues/2501
[#2524]: https://github.com/google/docsy/pull/2524
[#2533]: https://github.com/google/docsy/pull/2533
[#2548]: https://github.com/google/docsy/pull/2548
[#2549]: https://github.com/google/docsy/pull/2549
[#939]: https://github.com/google/docsy/issues/939
[0.13.0]: /zh/project/about/changelog/#v0.13.0
[0.14.0]: https://github.com/google/docsy/releases/v0.14.0
[0.14.1]: https://github.com/google/docsy/releases/v0.14.1
[0.14.2]: https://github.com/google/docsy/releases/v0.14.2
[0.14.3]: https://github.com/google/docsy/releases/v0.14.3
[高级样式定制]: /zh/docs/content/lookandfeel/#advanced-style-customization
[CL@0.14.0]: /zh/project/about/changelog/#v0.14.0
[CL@0.14.1]: /zh/project/about/changelog/#v0.14.1
[CL@0.14.2]: /zh/project/about/changelog/#v0.14.2
[CL@0.14.3]: /zh/project/about/changelog/#v0.14.3
[experimental]: /zh/project/about/changelog/#experimental
[hugo-0.152.0+]: /zh/blog/2026/hugo-0.152.0+/
[正式支持]: /zh/project/about/changelog/#official-support
[项目样式文件]: /zh/docs/content/lookandfeel/#project-style-files
[项目样式]: /zh/docs/content/lookandfeel/#project-styles
[技术债务]: https://martinfowler.com/bliki/TechnicalDebt.html
[测试清单]: /zh/blog/2025/0.12.0/#testing-checklist
[升级到 Docsy 0.12.0]: /zh/blog/2025/0.12.0/
[升级到 Docsy 0.13.0]: /zh/blog/2025/0.13.0/