从 Docsy 0.11.0 升级到 0.12.0

我们没有为 0.12.0 发布版本公告，因此借此机会完整介绍从 0.11.0 升级到 0.12.0 的过程。

摘要：Docsy 0.12.0 的主要破坏性变更来自 Hugo 的新模板系统，它改变了 layouts 子目录和文件名。

本文将依次完成以下升级：

• Docsy：0.11.0 → 0.12.0
• Hugo：0.136.2 → 0.147.5¹
• Node：LTS 20 → LTS 22¹

流程概览

1. 更新 Docsy 与 Hugo 版本
2. 移动自定义布局文件与目录
3. 检查其他必要变更
4. 测试站点

更新 Docsy、Hugo 及其他依赖

1. 更新 Node.js

Docsy 正式支持当前活跃的 Node.js LTS 版本。在 0.12.0 发布时，该版本是 Node.js 22。建议使用 nvm 更新：

nvm install --lts

该命令会安装最新 LTS，并在当前 Shell 会话中选中它（适用于 Linux 与 macOS）。

2. 更新 Docsy

• 使用 NPM：

  BASH

  npm install --save-dev google/docsy#semver:0.12.0

• 使用 Hugo Module：

  BASH

  hugo mod get -u github.com/google/[email protected]

• 使用 Git Submodule：

  BASH

  cd themes/docsy
  git fetch --tags
  git checkout v0.12.0
  cd ../..
  git add themes/docsy

3. 更新 Hugo

先把 Hugo 更新到 0.147.5，即使最终目标是更高版本也应如此。建议在完成 Docsy 升级后，再通过独立步骤升级到更高版本。

具体方法取决于项目如何管理 Hugo 依赖。使用 hugo-extended 的项目应更新 NPM 软件包版本，同时更新 NPM Lockfile 或缓存键，强制刷新 CI/CD 缓存。例如：

npm install --save-exact -D [email protected]

4. 安装依赖

使用 Git Submodule 时，安装 Docsy 依赖：

npm install
(cd themes/docsy && npm install)

移动自定义布局文件与目录

为了与 Hugo 的新模板系统保持一致，Docsy v0.12.0 重新组织了 layouts 目录²。这不是强制要求，但建议按以下方式更新项目布局文件与目录，使其符合 Hugo 新结构：

• 将 _markup 上移一级：

  TEXT

  layouts/_default/_markup/  → layouts/_markup/

• 为子目录添加下划线前缀：

  TEXT

  layouts/partials/     → layouts/_partials/
  layouts/shortcodes/   → layouts/_shortcodes/

• 移动并重命名分类文件（如适用）：

  TEXT

  layouts/_default/taxonomy.html → layouts/term.html
  layouts/_default/terms.html    → layouts/taxonomy.html

以下命令可以帮助移动自定义布局文件与目录 ：

1. 移动自定义布局文件与目录：

   BASH

   # If you have custom partials
   git mv layouts/partials/* layouts/_partials/
   
   # If you have custom shortcodes
   git mv layouts/shortcodes/* layouts/_shortcodes/
   
   # If you have custom markup render hooks
   git mv layouts/_default/_markup/* layouts/_markup/
   
   # If you have custom taxonomy layouts
   git mv layouts/_default/taxonomy.html layouts/term.html
   git mv layouts/_default/terms.html layouts/taxonomy.html
   
   # Clean up empty directories
   rmdir layouts/partials layouts/shortcodes layouts/_default/_markup layouts/_default

2. 更新 Docsy 模板引用。

   如果 layouts/_markup/render-heading.html 引用了 Docsy 标题模板：

   DIFF

   - {{ template "_default/_markup/td-render-heading.html" . -}}
   + {{ partial "td/render-heading.html" . -}}
   

   请注意，td 前缀从文件名移到了目录路径。

检查其他必要变更

1. 图片指纹

如果项目 CSS/SCSS 没有 使用 blocks/cover 首屏/背景图片，请跳过本步骤。

Hugo 会生成新的图片指纹。在 CSS/SCSS 中引用首屏/背景图片路径的项目，需要更新为新指纹；严格配置内容安全策略（CSP）的项目也包括在内。

1. 构建站点：npm run build；
2. 在 public 或 resources/_gen/images/ 中检查带新指纹的图片文件名；
3. 更新样式表中的引用。

2. 分类文件

如果项目覆盖分类布局，除了移动文件，还要：

• 交换 布局文件；
• 将 terms 文件名改为 单数：terms.html → term.html。

CLI 命令见移动布局文件步骤。

3. 内部布局 content.html 文件重命名

如果项目覆盖 Docsy layouts/**/content.html 文件：

• 为文件名添加 _td- 前缀：content.html → _td-content.html。

受影响文件如下：

layouts/_td-content-after-header.html
layouts/_td-content.html
layouts/blog/_td-content.html

测试站点

构建站点并检查错误，尤其是找不到模板和布局文件缺失：

npm run build

建议同时执行开发构建与生产构建。

随后启动站点，确认渲染结果符合预期。例如：

npm run serve

测试清单

使用以下清单确认升级成功：

• 构建成功，且没有错误、警告或弃用通知；CSS 与其他资源均已渲染；
• 首页、文档页、博客文章等关键页面可以加载，没有 404 或布局损坏；
• 导航链接可解析，面包屑显示当前路径，当前分区正确高亮；
• 移动端或平板上导航可用，关键页面没有横向滚动；
• 外部链接显示预期样式，例如图标；
• 标题自链接工作正常且样式正确；
• 深色模式切换正常（如启用）；
• 自定义短代码正确渲染（如使用）；
• 搜索返回预期结果（如使用）；
• 打印预览正确（如使用）。

参考资料

完整发布说明见：

• Docsy v0.12.0 Changelog
• 从 0.136.2（或项目起始版本）到 0.147.5 的 Hugo 发布说明

其他参考资料：

• Hugo 0.146.0 模板系统
• 0.11.0 版本亮点
• 0.11.0 Changelog
• Docsy Issue #2243：适配 Hugo v0.146.0 新模板系统
• 0.13.0 发布报告与升级指南——从 0.12.0 升级到 0.13.0