# 0.16.0 发布报告与升级指南

> Docsy 以 @docsy/theme 发布到 npm。本版还把主题移动到 theme/，提高 Hugo 最低版本，并删除默认 Favicon、改用自动发现；各项变更均附升级操作。

---

LLMS index: [llms.txt](/oink.pgsty.com/llms.txt)

---

<!-- markdownlint-disable descriptive-link-text no-space-in-emphasis -->

<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-cubes text-primary fa-lg"></i>
  <span>**[一等 npm 支持](#npm-registry)**：从 Registry 安装 Docsy，以及[更多变化][more]</span>
- <i class="fa-solid fa-star text-info fa-lg"></i> <span>**[Favicon](#favicons)**：把图标放进
  `static/`，其余工作交给 Docsy</span>
- <i class="fa-solid fa-bolt text-warning fa-lg"></i>
  <span>**[共享页面框架](#shared-chrome)**（实验性）：大幅加速大型站点链接检查的构建模式</span>
- <i class="fa-solid fa-robot text-info fa-lg"></i>
  <span>**[面向智能体的升级指南](#upgrading-with-ai)**：可以直接交给 AI 助手</span>

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


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

- **现代化打包**：
  - [移动主题目录](#theme-folder)：每种安装方式只需修改一行路径；
  - Hugo Module 现在[通过 npm 获取 Bootstrap 与 Font Awesome](#npm-deps)；
  - 非 RTL 站点的 [PostCSS 改为按需启用](#postcss)；
  - [Docsy 发布到 npm Registry](#npm-registry)：新增 `@docsy/theme` 软件包。
- **[Hugo 最低版本提高到 0.160.1](#hugo)**：原为 0.146.0；
- **新功能**：
  - 从 `static/` [自动发现 Favicon](#favicons)；
  - [共享页面框架构建模式](#shared-chrome)（实验性）。
- [其他重要变更](#other-notable-changes)，以及[维护者相关变更](#for-maintainers)：仓库软件包布局、构建与测试守卫。

## 准备升级？<a id="breaking-changes"></a> {#ready-to-upgrade}

- :warning: 请遵守[步骤顺序][]，避免破坏构建；
- 审阅 <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> [移动主题目录](#theme-folder)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Hugo 最低版本](#hugo)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [删除默认 Favicon](#favicons)；
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i>
    [通过 npm 获取 Bootstrap 与 Font Awesome](#npm-deps)。
- 如果站点尚未使用 Hugo 0.164.0 干净构建，请阅读配套
  [Hugo 0.158+ 升级指南][hugo-upgrade]；
- 可以快速浏览：
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [Docsy 发布到 npm Registry](#npm-registry)；
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [Favicon 自动发现](#favicons)；
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 实验性[共享页面框架构建模式](#shared-chrome)；
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> [非 RTL 站点按需启用 PostCSS](#postcss)；
  - [其他重要变更](#other-notable-changes)与[维护者相关变更](#for-maintainers)。
- <i class="fa-solid fa-rocket text-primary px-1"></i>
  可以自行[升级到 0.16.0](#upgrade)，或[请 AI 智能体协助](#upgrading-with-ai)。

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 移动主题目录 {#theme-folder}

Docsy 的标准主题树从仓库根目录移动到 `theme/`，这是 0.16.0 最主要的结构变更。

对多数站点而言，升级有意保持简洁：只需更新 Hugo 查找主题的位置。

这样可以保持安装主题表面精简，将维护者工具、测试和发布自动化隔离在主题之外。

### 操作 {#theme-folder-actions}

下面的版本更新命令应按[步骤顺序][]执行——位于 Node 与 Hugo 更新之后。采用当前 Shell 兼容的方式，把
`VERSION` 设为准备安装的 Docsy 版本，例如：

```sh
VERSION=v0.16.0
```

#### Hugo Module 站点 {#hugo-module-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点以 Hugo Module 形式导入 Docsy。

把 Module 导入路径从 `github.com/google/docsy` 改为
`github.com/google/docsy/theme`：

```yaml
# OLD
module:
  imports:
    - path: github.com/google/docsy

# NEW
module:
  imports:
    - path: github.com/google/docsy/theme
```

然后更新 Module：

```sh
hugo mod get github.com/google/docsy/theme@$VERSION
hugo mod tidy
```

仍然请求普通发布版本。验证更新时，确认站点 `go.mod` 已按所请求版本记录
`github.com/google/docsy/theme`。

#### 通过 GitHub npm 安装 {#npm-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点通过 npm 从 GitHub 安装 Docsy。

从 GitHub 进行 npm 安装现在只用于[开发与测试][正式支持策略]；生产环境应迁移到新的
[`@docsy/theme` Registry 软件包](#npm-registry)，其[操作](#npm-registry-actions)覆盖这种起始状态。

如果继续使用 GitHub 安装，请修改主题路径：

```yaml
# OLD
theme: docsy
themesDir: node_modules

# NEW
theme: docsy/theme
themesDir: node_modules
```

安装命令形式保持不变：

```sh
npm install --save-dev google/docsy#semver:$VERSION
```

#### Git Clone 或 Git Submodule 站点 {#clone-submodule-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点以 Clone 或 Git
Submodule 形式把 Docsy 放在 `themes/docsy/` 下。

修改主题路径：

```yaml
# OLD
theme: docsy

# NEW
theme: docsy/theme
```

随后采用现有更新流程，把 Clone 或 Submodule 更新到
`$VERSION`。例如，Submodule 可以运行：

```sh
git -C themes/docsy fetch --tags && git -C themes/docsy checkout $VERSION
```

然后从 `themes/docsy/` 内重新运行主题安装步骤：

```sh
npm run postinstall
```

> [!WARNING]
>
> 请运行 `npm run postinstall`，不要运行 `npm install`：在 `themes/docsy/`
> 中直接执行后者，会拉取仓库的维护者 Workspace，而不仅是主题运行时依赖。

全新的 Clone 或 Submodule 配置见[其他安装选项][]。

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Hugo 最低版本提高到 0.160.1 {#hugo}

Docsy 0.16.0 把主题支持的最低 Hugo 版本从 0.146.0 提高到
**0.160.1**。该最低版本反映此范围内三项变化：

- 主题模板使用 Hugo **0.158.0** 引入的语言 API；更旧版本会出现模板错误；
- 主题的 [npm 来源依赖](#npm-deps)依靠 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-upgrade]。

“最低 Hugo 版本”与项目锁定并测试的“正式支持版本”之间的区别，现在已经写入 Docsy
[正式支持策略][]。

### 操作 {#hugo-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用于所有升级到 Docsy 0.16.0 的项目。**

- 升级到 Hugo 0.160.1 或更高版本，优先选择 Hugo
  0.164.0；安装命令见 Hugo 指南的[升级到 Hugo
  0.164.0][hugo-upgrade-install]一节；
- 站点声明 `module.hugoVersion.min` 时，将其设为至少 `0.160.1`；
- 多语言站点或覆盖语言相关模板的站点，按照 Hugo 指南完成[语言 API 重命名][hugo-language-apis]。

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 通过 npm 获取 Bootstrap 与 Font Awesome {#npm-deps}

**适用于 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`][hugo-npm-pack]将其交付给项目。这也淘汰了主题生成的 Go
Module Require、Module 同步脚本与 Bootstrap `rfs` Vendor 变通项。

### 操作 {#npm-deps-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点以 Hugo Module 形式导入 Docsy。

更新 Docsy Module 后，汇总并安装主题 npm 依赖：

```sh
hugo mod npm pack
npm install
```

每次更新 Docsy 都应重新运行
`hugo mod npm pack`；依赖集合发生漂移时，Hugo 会发出警告。

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Docsy 发布到 npm Registry {#npm-registry}

Hugo 把
[Module 的 npm 依赖][hugo-npm-pack]提升为一等能力，[Docsy 顺势跟进](#npm-deps)，又进一步将主题本身以
[`@docsy/theme`][] 发布到 npm
Registry。Registry 软件包以普通 npm 依赖交付主题、Bootstrap 与 Font
Awesome，无需额外工具链或安装步骤：

```sh
npm install --save-dev @docsy/theme
```

配置详情见[将 Docsy 作为 NPM 软件包][]。

Registry 版本属于正式版本：[正式支持策略][]现在把 npm 软件包与 Hugo
Module、GitHub Release Tag 并列。

### 操作 {#npm-registry-actions}

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i>
**适用条件**：站点通过 npm 从 GitHub 安装 Docsy（`google/docsy#semver:…`）。

- 迁移到 Registry 软件包：

  ```sh
  npm uninstall docsy
  npm install --save-dev @docsy/theme
  ```

- 更新站点配置中的主题路径；YAML 中必须保留引号：

  ```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
  ```

## <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 非 RTL 站点按需启用 PostCSS {#postcss}

Docsy 现在只在站点含有 RTL 语言——需要 PostCSS 插件
`rtlcss`——或者提供自有 PostCSS 配置时运行
`postCSS`。其他站点完全不再需要 PostCSS 工具链。

删除这一步不会损失功能：对于非 RTL
CSS，它唯一的工作是 Autoprefixer，而现代浏览器已经基本不再需要供应商前缀。Docsy 发布的 CSS 面向 Browserslist
`defaults` 浏览器（见[安装
PostCSS][]）；针对这些浏览器，Autoprefixer 处理后的主题 CSS 逐字节不变。因此，这一步早已悄然变成只增加工具链要求、却没有实际输出变化的空操作。

### 操作 {#postcss-actions}

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **适用条件**：站点没有 RTL 语言，也没有自己的
`postcss.config.*`。

- 从依赖中删除 `autoprefixer`、`postcss` 与 `postcss-cli`；构建不再需要它们。

**适用条件**：站点需要 PostCSS：包含 RTL 语言，或希望为自有 CSS 使用 Autoprefixer/其他 PostCSS 插件。

- 按照[安装 PostCSS][]保留工具链。项目根目录的 `postcss.config.{js,mjs,cjs}`
  会让生产构建重新启用 PostCSS 步骤。

## <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> Favicon {#favicons}

Docsy 不再提供默认 Favicon 图稿。站点现在自行拥有 Favicon 文件，从而避免下游项目误发带 Docsy 品牌的图标。

为保持常见场景简单，Docsy 默认 Favicon Partial 会从站点 `static/`
目录自动发现并链接使用约定名称的文件。站点只要提供
`static/favicon.ico`、`static/favicon.svg`、`static/apple-touch-icon.png`
等文件，就会获得对应 `<link>` 元素，无需覆盖 Partial。

完整文件名列表与辅助命令见[添加 Favicon][]。

### 操作 {#favicons-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **适用条件**：站点依赖 Docsy 随附的默认 Favicon。

- 把自有 Favicon 文件放到 `static/` 下；
- 构建站点并检查生成页面的 `<head>`，确认预期图标链接存在。

**适用条件**：站点覆盖 `layouts/_partials/favicons.html`。

- 需要自定义 Link Tag、非默认文件名、Web App
  Manifest 或其他平台图标时，保留覆盖项；
- 否则，可以删除覆盖项，改用默认自动发现行为。

如果已有源 SVG 并安装了 ImageMagick，可以使用新增辅助程序生成常见栅格文件。通过 npm 安装 Docsy 时：

```sh
npx --no-install gen-favicons static/favicon.svg static/
```

其他安装方式的等效命令见[添加 Favicon][]。

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 共享页面框架构建模式 {#shared-chrome}

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 向组件化迈出的一小步。配置、保留或恢复的契约以及当前限制见[页面框架构建模式][chrome]。该功能为[实验性][]，未来可能变化。

### 操作 {#shared-chrome-actions}

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i>
**适用条件**：希望加快链接检查、输出 Diff 或预览，尤其是大型或多语言站点。

- 可以在链接检查或 CI 等非生产构建中把 `td.chrome` 设为 `shared`（例如
  `HUGO_PARAMS_TD_CHROME=shared`），发布输出仍使用 `full`；
- 暂时不要依赖 `shared` 模式生成生产 HTML，详见[页面框架构建模式][chrome]。

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

- **俄语界面文字**：与英文原文同步并完成校正。

本项及其他所有变更见 [0.16.0][] 发布页。

## 维护者相关变更 {#for-maintainers}

本节变更影响 Docsy 维护者与贡献者，不影响使用方站点。

### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 仓库与软件包布局 {#package-layout}

Docsy 仓库现在具有更清晰的软件包边界：

- `theme/` 包含使用方站点所需的主题文件；
- `theme/package.json` 管理主题运行时 npm 依赖；
- `docsy.dev/` 管理网站构建与站点专属工具；
- 仓库根目录管理 Workspace 编排、发布工具与测试。

面向用户的影响就是[移动主题目录](#theme-folder)中说明的主题路径变更。

### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> 构建与测试守卫 {#build-test-guards}

Docsy 测试套件现在包含 Hugo 弃用输出守卫与小型 Fixture 站点回归测试。这些检查帮助验证 Hugo
0.158.0 至 0.164.0 升级范围以及新的主题目录安装矩阵。项目链接检查也从无人维护的 htmltest 迁移到
[Lychee][]，并提交链接缓存，实现快速、可复现的检查。

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

按照[更新 Docsy][]操作，并注意：



- :warning: 请遵守[步骤顺序][]，避免破坏构建；
- 应用本版[主题目录移动](#theme-folder-actions)中的配置变更；“更新 Docsy”页面已经展示移动后的安装路径；
- 使用以下版本：[^vers-note]
  - **[Docsy][update-theme]**：[0.15.0][] → [0.16.0][]
  - **[Hugo][update-hugo]**：[0.157.0][] →
    [0.164.0][hugo-supported-version]；主题最低版本：[0.160.1][]
  - **[Node][update-node]**：LTS 24（不变）
- 记得[审阅主题覆盖项][overrides]：本版移动并重做了站点经常覆盖的主题文件。

[^vers-note]:
    与 `docsy.dev`
    测试使用的 Hugo 锁定版本和主题声明的 Hugo 最低版本一致。更高版本的 Hugo 或 Node 可能可以工作，详见[正式支持策略][]。

### <i class="fa-solid fa-robot text-info px-1"></i> 使用 AI 升级？ {#upgrading-with-ai}

把本文与配套
[Hugo 指南][hugo-upgrade]一起交给助手作为上下文：两篇文章也可直接作为操作说明，包含适用条件、按安装模式区分的操作、验证步骤与基本检查。审阅期间，AI 智能体已经在
[Docsy 示例站][docsy-example]上执行过这些说明。

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

### <i class="fa-solid fa-square-check text-primary px-1"></i> 基本检查 {#sanity-checks}

除[通用站点检查][check]外，本版还应确认：

- [ ] [检查 Favicon 输出](#favicons-actions)，尤其是过去依赖 Docsy 默认图标的站点；
- [ ] 多语言站点按照 Hugo 指南的[语言 API 重命名][hugo-language-apis]，审阅语言配置项与自定义语言模板覆盖；
- [ ] 确认当前安装方式已经[采用新的主题路径](#theme-folder-actions)；
- [ ] Hugo Module 站点确认[构建没有 SCSS 导入错误](#npm-deps-actions)。

</section>

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

0.16.0 完成主题目录移动与相关打包路线，包括把主题发布到 npm
Registry。下一版工作在 [0.17.0 发布准备][#2691]中跟踪。

<!-- 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

## 参考资料 {#references}

关于本版：

- [0.16.0][CL@0.16.0] Changelog 条目
- [0.16.0][] 发布页
- [0.16.0 发布准备 Issue（#2615）][#2615]
- [0.15.0][compare-0.15.0] 之后的 Git 历史

<!-- prettier-ignore-start -->
[#2615]: https://github.com/google/docsy/issues/2615
[#2691]: https://github.com/google/docsy/issues/2691
[0.15.0]: https://github.com/google/docsy/releases/v0.15.0
[0.16.0]: https://github.com/google/docsy/releases/v0.16.0
[0.157.0]: https://github.com/gohugoio/hugo/releases/tag/v0.157.0
[0.160.1]: https://github.com/gohugoio/hugo/releases/tag/v0.160.1
[hugo-supported-version]:
  <https://github.com/gohugoio/hugo/releases/tag/v0.164.0>
[`@docsy/theme`]: https://www.npmjs.com/package/@docsy/theme
[添加 Favicon]: /zh/docs/content/iconsimages/#add-your-favicons
[check]: /zh/docs/update/#check
[chrome]: /zh/docs/deployment/chrome/
[CL@0.16.0]: /zh/project/about/changelog/#v0.16.0
[compare-0.15.0]: https://github.com/google/docsy/compare/v0.15.0...v0.16.0
[将 Docsy 作为 NPM 软件包]: /zh/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
[docsy-example]: https://github.com/google/docsy-example
[实验性]: /zh/project/about/changelog/#experimental
[hugo-language-apis]: hugo-0.158.0+/#language-apis
[hugo-upgrade]: hugo-0.158.0+/
[hugo-upgrade-install]: hugo-0.158.0+/#upgrade
[hugo-npm-pack]: https://gohugo.io/hugo-modules/nodejs-dependencies/
[安装 PostCSS]: /zh/docs/get-started/docsy-as-module/installation-prerequisites/#install-postcss
[Lychee]: https://github.com/lycheeverse/lychee
[more]: #npm-deps
[正式支持策略]: /zh/project/about/changelog/#official-support
[其他安装选项]: /zh/docs/get-started/other-options/
[步骤顺序]: /zh/docs/update/#update-order
[overrides]: /zh/docs/update/#update-overrides
[更新 Docsy]: /zh/docs/update/
[update-hugo]: /zh/docs/update/#update-hugo
[update-node]: /zh/docs/update/#update-node
[update-theme]: /zh/docs/update/#update-theme
<!-- prettier-ignore-end -->