0.16.0 发布报告与升级指南
- 一等 npm 支持：从 Registry 安装 Docsy，以及更多变化
- Favicon：把图标放进
static/，其余工作交给 Docsy - 共享页面框架（实验性）：大幅加速大型站点链接检查的构建模式
- 面向智能体的升级指南：可以直接交给 AI 助手
发布摘要
- 现代化打包：
- 移动主题目录：每种安装方式只需修改一行路径；
- Hugo Module 现在通过 npm 获取 Bootstrap 与 Font Awesome；
- 非 RTL 站点的 PostCSS 改为按需启用；
- Docsy 发布到 npm Registry：新增
@docsy/theme软件包。
- Hugo 最低版本提高到 0.160.1：原为 0.146.0；
- 新功能：
- 从
static/自动发现 Favicon； - 共享页面框架构建模式（实验性）。
- 从
- 其他重要变更，以及维护者相关变更：仓库软件包布局、构建与测试守卫。
准备升级？
- ⚠️ 请遵守步骤顺序，避免破坏构建；
- 审阅 BREAKING 变更：
- 如果站点尚未使用 Hugo 0.164.0 干净构建，请阅读配套 Hugo 0.158+ 升级指南；
- 可以快速浏览：
- 可以自行升级到 0.16.0，或请 AI 智能体协助。
/ 移动主题目录
Docsy 的标准主题树从仓库根目录移动到 theme/，这是 0.16.0 最主要的结构变更。
对多数站点而言，升级有意保持简洁：只需更新 Hugo 查找主题的位置。
这样可以保持安装主题表面精简，将维护者工具、测试和发布自动化隔离在主题之外。
操作
下面的版本更新命令应按步骤顺序执行——位于 Node 与 Hugo 更新之后。采用当前 Shell 兼容的方式，把
VERSION 设为准备安装的 Docsy 版本，例如：
VERSION=v0.16.0
Hugo Module 站点
适用条件：站点以 Hugo Module 形式导入 Docsy。
把 Module 导入路径从 github.com/google/docsy 改为
github.com/google/docsy/theme：
# OLD
module:
imports:
- path: github.com/google/docsy
# NEW
module:
imports:
- path: github.com/google/docsy/theme
然后更新 Module：
hugo mod get github.com/google/docsy/theme@$VERSION
hugo mod tidy
仍然请求普通发布版本。验证更新时，确认站点 go.mod 已按所请求版本记录
github.com/google/docsy/theme。
通过 GitHub npm 安装
适用条件：站点通过 npm 从 GitHub 安装 Docsy。
从 GitHub 进行 npm 安装现在只用于开发与测试；生产环境应迁移到新的
@docsy/theme Registry 软件包，其操作覆盖这种起始状态。
如果继续使用 GitHub 安装，请修改主题路径：
# OLD
theme: docsy
themesDir: node_modules
# NEW
theme: docsy/theme
themesDir: node_modules
安装命令形式保持不变：
npm install --save-dev google/docsy#semver:$VERSION
Git Clone 或 Git Submodule 站点
适用条件：站点以 Clone 或 Git
Submodule 形式把 Docsy 放在 themes/docsy/ 下。
修改主题路径：
# OLD
theme: docsy
# NEW
theme: docsy/theme
随后采用现有更新流程，把 Clone 或 Submodule 更新到
$VERSION。例如，Submodule 可以运行：
git -C themes/docsy fetch --tags && git -C themes/docsy checkout $VERSION
然后从 themes/docsy/ 内重新运行主题安装步骤：
npm run postinstall
请运行 npm run postinstall，不要运行 npm install：在 themes/docsy/
中直接执行后者，会拉取仓库的维护者 Workspace，而不仅是主题运行时依赖。
全新的 Clone 或 Submodule 配置见其他安装选项。
Hugo 最低版本提高到 0.160.1
Docsy 0.16.0 把主题支持的最低 Hugo 版本从 0.146.0 提高到 0.160.1。该最低版本反映此范围内三项变化：
- 主题模板使用 Hugo 0.158.0 引入的语言 API；更旧版本会出现模板错误；
- 主题的 npm 来源依赖依靠 Hugo 0.159.0 新增的 Workspace 感知
hugo mod npm pack支持。旧版本中，打包步骤会成功退出，却写入空依赖列表；问题直到后续 SCSS 导入错误才暴露，很难追查，而 Hugo 最低版本警告是唯一早期信号； - 0.160.1 排除了 0.159.2 至 0.160.0 范围内的已知回归。
Docsy 项目构建与示例站使用 Hugo 0.164.0 验证。0.158.0 至 0.164.0 的详细变化见配套 Hugo 0.158+ 升级指南。
“最低 Hugo 版本”与项目锁定并测试的“正式支持版本”之间的区别，现在已经写入 Docsy 正式支持策略。
操作
适用于所有升级到 Docsy 0.16.0 的项目。
- 升级到 Hugo 0.160.1 或更高版本，优先选择 Hugo 0.164.0；安装命令见 Hugo 指南的升级到 Hugo 0.164.0一节；
- 站点声明
module.hugoVersion.min时，将其设为至少0.160.1； - 多语言站点或覆盖语言相关模板的站点，按照 Hugo 指南完成语言 API 重命名。
/ 通过 npm 获取 Bootstrap 与 Font Awesome
适用于 Hugo
Module 安装方式，它需要新增一步升级操作。通过 npm 从 GitHub 安装，或使用 Clone/Submodule 的站点不受影响——它们仍通过 Docsy 的
postinstall 获取 Bootstrap 与 Font Awesome。
Docsy 现在从 npm 获取 Bootstrap 与 Font
Awesome，而不再把二者各自的 GitHub 仓库作为 Hugo
Module 导入。旧导入方式只是变通方案，因为两个项目都不发布 Go
Module。Hugo 的一等 npm Module 支持使它们不再必要：theme/package.json
声明 Bootstrap 与 Font
Awesome，hugo mod npm pack将其交付给项目。这也淘汰了主题生成的 Go
Module Require、Module 同步脚本与 Bootstrap rfs Vendor 变通项。
操作
适用条件：站点以 Hugo Module 形式导入 Docsy。
更新 Docsy Module 后，汇总并安装主题 npm 依赖：
hugo mod npm pack
npm install
每次更新 Docsy 都应重新运行
hugo mod npm pack；依赖集合发生漂移时，Hugo 会发出警告。
Docsy 发布到 npm Registry
Hugo 把
Module 的 npm 依赖提升为一等能力，Docsy 顺势跟进，又进一步将主题本身以
@docsy/theme 发布到 npm
Registry。Registry 软件包以普通 npm 依赖交付主题、Bootstrap 与 Font
Awesome，无需额外工具链或安装步骤：
npm install --save-dev @docsy/theme
配置详情见将 Docsy 作为 NPM 软件包。
Registry 版本属于正式版本：正式支持策略现在把 npm 软件包与 Hugo Module、GitHub Release Tag 并列。
操作
适用条件：站点通过 npm 从 GitHub 安装 Docsy（google/docsy#semver:…）。
-
迁移到 Registry 软件包：
npm uninstall docsy npm install --save-dev @docsy/theme -
更新站点配置中的主题路径；YAML 中必须保留引号：
# OLD (docsy/theme for 0.16, docsy before the theme folder move) theme: docsy/theme themesDir: node_modules # NEW theme: '@docsy/theme' themesDir: node_modules
非 RTL 站点按需启用 PostCSS
Docsy 现在只在站点含有 RTL 语言——需要 PostCSS 插件
rtlcss——或者提供自有 PostCSS 配置时运行
postCSS。其他站点完全不再需要 PostCSS 工具链。
删除这一步不会损失功能：对于非 RTL
CSS，它唯一的工作是 Autoprefixer，而现代浏览器已经基本不再需要供应商前缀。Docsy 发布的 CSS 面向 Browserslist
defaults 浏览器（见安装
PostCSS）；针对这些浏览器，Autoprefixer 处理后的主题 CSS 逐字节不变。因此，这一步早已悄然变成只增加工具链要求、却没有实际输出变化的空操作。
操作
适用条件：站点没有 RTL 语言，也没有自己的
postcss.config.*。
- 从依赖中删除
autoprefixer、postcss与postcss-cli；构建不再需要它们。
适用条件：站点需要 PostCSS：包含 RTL 语言，或希望为自有 CSS 使用 Autoprefixer/其他 PostCSS 插件。
- 按照安装 PostCSS保留工具链。项目根目录的
postcss.config.{js,mjs,cjs}会让生产构建重新启用 PostCSS 步骤。
/ Favicon
Docsy 不再提供默认 Favicon 图稿。站点现在自行拥有 Favicon 文件，从而避免下游项目误发带 Docsy 品牌的图标。
为保持常见场景简单，Docsy 默认 Favicon Partial 会从站点 static/
目录自动发现并链接使用约定名称的文件。站点只要提供
static/favicon.ico、static/favicon.svg、static/apple-touch-icon.png
等文件，就会获得对应 <link> 元素，无需覆盖 Partial。
完整文件名列表与辅助命令见添加 Favicon。
操作
适用条件：站点依赖 Docsy 随附的默认 Favicon。
- 把自有 Favicon 文件放到
static/下； - 构建站点并检查生成页面的
<head>，确认预期图标链接存在。
适用条件：站点覆盖 layouts/_partials/favicons.html。
- 需要自定义 Link Tag、非默认文件名、Web App Manifest 或其他平台图标时，保留覆盖项；
- 否则，可以删除覆盖项，改用默认自动发现行为。
如果已有源 SVG 并安装了 ImageMagick，可以使用新增辅助程序生成常见栅格文件。通过 npm 安装 Docsy 时：
npx --no-install gen-favicons static/favicon.svg static/
其他安装方式的等效命令见添加 Favicon。
共享页面框架构建模式
Docsy 0.16.0 新增实验性的 共享页面框架构建模式。设置 td.chrome = shared
后，Docsy 会在每种语言的一个供体页面上渲染重复页面框架——顶部导航、Footer 与左侧导航——再通过主题的
chrome-nav.js 运行时，在浏览器中把它恢复到其他页面。默认 td.chrome = full
模式与过去一样，为每页渲染完整框架。
它改善的是贡献者与 CI 体验，而非改变发布站点。共享模式把大量重复框架链接集中在一个页面，因此链接检查、输出 Diff 与预览——也就是站点工作的外层循环——成本会显著降低；JavaScript 运行后，读者仍会得到完整页面。
既有的大型站点导航优化仍然保留：页面数超过 sidebar_cache_limit 时，full
构建仍会把左侧导航渲染一次，作为共享缓存菜单。0.16.0 只是把激活逻辑从每页内联 jQuery 移到随主题提供的
chrome-nav.js；该脚本现在无论构建模式如何都会在每页加载。
shared
模式是 Docsy 向组件化迈出的一小步。配置、保留或恢复的契约以及当前限制见页面框架构建模式。该功能为实验性，未来可能变化。
操作
适用条件：希望加快链接检查、输出 Diff 或预览，尤其是大型或多语言站点。
- 可以在链接检查或 CI 等非生产构建中把
td.chrome设为shared（例如HUGO_PARAMS_TD_CHROME=shared），发布输出仍使用full； - 暂时不要依赖
shared模式生成生产 HTML，详见页面框架构建模式。
其他重要变更
- 俄语界面文字：与英文原文同步并完成校正。
本项及其他所有变更见 0.16.0 发布页。
维护者相关变更
本节变更影响 Docsy 维护者与贡献者，不影响使用方站点。
仓库与软件包布局
Docsy 仓库现在具有更清晰的软件包边界：
theme/包含使用方站点所需的主题文件；theme/package.json管理主题运行时 npm 依赖；docsy.dev/管理网站构建与站点专属工具；- 仓库根目录管理 Workspace 编排、发布工具与测试。
面向用户的影响就是移动主题目录中说明的主题路径变更。
构建与测试守卫
Docsy 测试套件现在包含 Hugo 弃用输出守卫与小型 Fixture 站点回归测试。这些检查帮助验证 Hugo 0.158.0 至 0.164.0 升级范围以及新的主题目录安装矩阵。项目链接检查也从无人维护的 htmltest 迁移到 Lychee，并提交链接缓存，实现快速、可复现的检查。
升级到 0.16.0
按照更新 Docsy操作，并注意：
- ⚠️ 请遵守步骤顺序，避免破坏构建；
- 应用本版主题目录移动中的配置变更；“更新 Docsy”页面已经展示移动后的安装路径；
- 使用以下版本：1
- 记得审阅主题覆盖项：本版移动并重做了站点经常覆盖的主题文件。
使用 AI 升级？
把本文与配套 Hugo 指南一起交给助手作为上下文：两篇文章也可直接作为操作说明，包含适用条件、按安装模式区分的操作、验证步骤与基本检查。审阅期间，AI 智能体已经在 Docsy 示例站上执行过这些说明。
基本检查
除通用站点检查外，本版还应确认：
- 检查 Favicon 输出，尤其是过去依赖 Docsy 默认图标的站点；
- 多语言站点按照 Hugo 指南的语言 API 重命名，审阅语言配置项与自定义语言模板覆盖；
- 确认当前安装方式已经采用新的主题路径；
- Hugo Module 站点确认构建没有 SCSS 导入错误。
接下来是什么？
0.16.0 完成主题目录移动与相关打包路线，包括把主题发布到 npm Registry。下一版工作在 0.17.0 发布准备中跟踪。
-
如果希望某项功能或修复进入后续版本，请为相关 Issue 或 PR 点赞投票；
-
如果 Docsy 对你有帮助，请考虑为仓库加星，表达支持。
参考资料
关于本版：
- 0.16.0 Changelog 条目
- 0.16.0 发布页
- 0.16.0 发布准备 Issue（#2615）
- 0.15.0 之后的 Git 历史