0.14.0 发布报告与升级指南

发布摘要

• 样式与定制：
  • 导航栏改进，包括可配置浅色/深色主题与可调整高度；
  • 标题别名与页内目标；
  • 重新组织内部 SCSS 文件。

    ⚠️ 如果你定制 Swagger UI，这会影响你的项目！

• 内容、短代码与国际化：
  • 新增 Markdown 告警语法；
  • blocks/cover 短代码变更；
  • 新增用于 Netlify 构建信息的短代码；
  • 国际化更新。
• 要求 Hugo 0.155.0 或更高版本；同时讨论破坏性变更与 sites.matrix 等新功能；
• 公开功能与内部功能：新增定义，明确定制表面、私有/内部功能和支持边界。

准备升级？

• 审阅 BREAKING 变更：
  • 样式与定制；
  • 标题别名与页内目标；
  • blocks/cover 短代码正文处理；
  • Hugo 0.155.0 要求与 0.153+ 破坏性变更；
  • （仅样式）Docsy 0.14.2 代码样式更新，适配浅色/深色模式。
• 可以快速浏览：
  • 新功能（寻找绿色对勾图标）；
  • 清理与改进机会（寻找对应图标）；
  • 其他重要变更。
• 准备好后，直接阅读升级到 0.14.0。

Markdown 告警语法

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

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

渲染结果如下：

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

操作（可选）

适用条件：项目使用 alert 短代码。可以考虑迁移到 Markdown 告警，以保持一致，并改善创作与工具支持：

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

样式与定制

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

导航栏样式改进

亮点：

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

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

导航栏 高度与样式 可通过以下变量调整（EXPERIMENTAL）：

• SCSS 变量：

  • $td-navbar-min-height
  • $td-navbar__main-min-height-mobile
• CSS 变量

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

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

操作：必需与可选

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

• / 导航栏浅色/深色主题：始终使用深色导航栏是 Docsy 早期限制，并不适合所有站点。现在可以选择最符合项目整体设计的主题。

  • 如果设计不要求深色导航栏，可以删除过去仅为强制深色而添加的覆盖项；
  • 如果设计确实要求深色导航栏，把 params.ui.navbar_theme 设为 dark，恢复旧行为（见详情）。

• 导航栏覆盖首屏：适用于定位导航栏首屏半透明 class 的项目。

  • 审阅并简化样式（见导航栏首屏图片半透明）；
  • 用 .td-navbar-transparent（与 .td-navbar-cover 配合）替代 .navbar-bg-on-scroll 与 .navbar-bg-onscroll--fade。

• 高度与变量：适用于自定义导航栏高度或样式的项目。使用新增变量与样式审阅并简化定制，见自定义导航栏。

• 导航栏 Partial 覆盖项：适用于覆盖导航栏 Partial 的项目。请审阅 _nav.html 的变更。

  layouts/_partials/navbar.html 编辑摘要

  变更前	变更后
  首屏半透明
  <nav> 只有 td-navbar-cover 项目使用 .navbar-bg-on-scroll、.navbar-bg-onscroll--fade	<nav> 同时获得 td-navbar-cover 与 td-navbar-transparent 删除旧 class
  浅色/深色主题
  <nav> 始终设置 data-bs-theme="dark"	仅当 params.ui.navbar_theme 为 "dark" 时设置 data-bs-theme="dark" 否则跟随站点主题

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

标题别名与页内目标

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

操作：必需与可选

• 适用条件：站点使用 td-offset-anchor，例如覆盖 blocks/lead.html、blocks/section.html 或 layouts/community/list.html。

  把 td-offset-anchor 重命名为 td-anchor-no-extra-offset，见实现说明。

• 滚动行为：适用于希望确保既有标题别名与页内目标正确滚动的项目。

  • 如果尚未采用，请把标题别名与页内目标改为 <a id="..."></a>；
  • 尤其应把 <span> 等非 Anchor 目标替换为 <a id="..."></a>，提高滚动可靠性；
  • 把 <a name="..."> 等旧目标改为基于 id 的目标。

更好地区分项目与内部 SCSS 文件

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

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

操作：必需与可选

适用条件：项目在 assets/scss/ 中存在下列文件，因为这意味着项目覆盖了 Docsy 内部 SCSS。²

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

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

@import 'table';

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

Swagger UI 样式定制

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

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

如果项目有 Swagger UI 样式定制，请按照上一节需要操作中的步骤处理。

blocks/cover 短代码变更

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

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

操作：必需与可选

• 适用条件：在 .html 内容文件中使用 blocks/cover，且正文包含 Markdown。

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

• 建议多数项目采用。³ 如果希望 blocks/cover 位于导航栏下方而不是其后，请在调用中加入 td-below-navbar 辅助 class，例如 height="auto td-below-navbar"。详见导航栏下方高度调整。

Hugo 要求与破坏性变更

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

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

/ 补丁更新 0.14.2

Docsy 0.14.2 包含以下变化：

• 对使用 td/code-dark 的站点，默认代码样式从 tango/onedark 改为 friendly/native（#2548）；
• 选择控制台代码块和复制代码时，现在只包含命令，不含输出（#2548）。详情见选择控制台代码块内容；
• 搜索表单新增 name 属性，改进语义与自动填充行为（#2549）。

操作：必需与可选

• 适用条件：使用 td/code-dark，而且希望恢复 tango/onedark 样式。请按照浅色/深色代码样式及其他配置操作；
• 验证控制台示例的复制代码行为——只复制命令——是否符合预期。恢复旧行为见选择控制台代码块内容。

Docsy 其他重要变更

国际化

变更摘要：

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

操作（可选）：适用于包含 i18n 文件的项目。可以借机清理并减少技术债务：

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

样式改进与修复

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

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

实验性额外样式：

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

详情见额外样式。

短代码

• 新增实验性 td/site-build-info/netlify 短代码，用于显示 Netlify 构建信息。见示例。

明确公开功能与内部主题功能

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

• 公开定制表面
• 私有/内部功能
• 实验性功能
• 破坏性变更
• 正式支持边界

升级到 0.14.0

升级步骤

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

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

接下来是什么？

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

目标与反馈

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

参考资料

关于本版：

• 0.14.0 至 0.14.3 的 Changelog 条目
• 0.14.3、0.14.2、0.14.1 与 0.14.0 发布页
• 0.14.0 发布准备 Issue（#2404）

其他参考资料：

• 配套 Hugo 0.152.0–0.155.x 升级指南
• 0.13.0 升级指南
• Hugo 发布说明

• ←上一页
• 下一页→