升级 on OINK 文档主题

0.16.0 发布报告与升级指南

Wed, 29 Jul 2026 00:00:00 +0000

亮点

一等 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 最低版本；
- 删除默认 Favicon；
- 通过 npm 获取 Bootstrap 与 Font Awesome。
如果站点尚未使用 Hugo 0.164.0 干净构建，请阅读配套 Hugo 0.158+ 升级指南；
可以快速浏览：
- Docsy 发布到 npm Registry；
- Favicon 自动发现；
- 实验性共享页面框架构建模式；
- 非 RTL 站点按需启用 PostCSS；
- 其他重要变更与维护者相关变更。
可以自行升级到 0.16.0，或请 AI 智能体协助。

/ 移动主题目录

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

Hugo 0.158.0–0.164.x 升级指南

Tue, 28 Jul 2026 00:00:00 +0000

本文是 Docsy 0.16.0 发布文章的配套指南；后者说明了 0.16.0 要求并验证过的 Hugo 版本。

升级摘要

以下情况适合阅读本指南：
- 升级到 Docsy 0.16.0；
- 只升级 Hugo。
审阅 BREAKING 变更：
- 由 Hugo 管理的 Node 工具要求 Node 22+；
- HTML 内容与符号链接的安全规则发生变化。
审阅 弃用项：
- 语言配置与模板 API；
- 图片处理配置与模板 API。
可以快速浏览：
- Markdown 链接转义；
- 图片 URL 变动；
- 模板与 Module 清理；
- 更快的构建与更严格的模板；
- 重要变化。
准备好后，直接阅读升级到 Hugo 0.164.0。

语言 API 弃用项（0.158.0）

Hugo 0.158.0 重命名了若干语言配置项和模板方法。按照 Hugo 的弃用时间线，旧名称会先记录弃用通知，随后升级为警告，最终变为错误。

0.15.0 发布报告与升级指南

Fri, 01 May 2026 00:00:00 +0000

亮点

智能体支持：llms.txt、Markdown 页面输出，以及“查看 Markdown”页面元数据链接
文档根站点：改进把文档发布到站点根路径的支持
版本菜单：更丰富的条目与更新后的导航栏渲染

发布摘要

智能体支持（实验性）：
- 生成 llms.txt；
- 为首页、分区和页面内容生成 Markdown 备用输出；
- 页面存在 Markdown 备用版本时显示“查看 Markdown”页面元数据链接。
文档根站点（实验性）：记录将 docs 分区发布到站点根路径的模式，并提供对应样例变体；
版本菜单条目：支持标题、分隔线、逐条页面链接行为和基于 Kind 的样式；
内容、短代码与国际化：
- 社区与 Footer 链接；
- card 短代码渲染；
- 国际化新增与更新。

准备升级？

审阅 BREAKING 变更：
- 社区与 Footer 链接；
- 版本菜单条目；
- 卡片短代码渲染（低风险）。
可以快速浏览：
- 新功能（寻找绿色对勾图标）；
- 清理与改进机会（寻找对应图标）；
- 其他重要变更。
准备好后，直接阅读升级到 0.15.0。

智能体支持

0.15.0 包含智能体支持的第一阶段实现，提供一组可选择启用的功能，帮助 AI 智能体与自动化工具发现并使用站点内容：

0.14.0 发布报告与升级指南

Tue, 10 Feb 2026 00:00:00 +0000

0.14.1 至 0.14.3 补丁更新

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

亮点

样式与定制：改进导航栏，重新组织 SCSS 文件
内容与本地化：新增 Markdown 告警语法并改进国际化
要求 Hugo 0.155.0，以及 0.153+ 的破坏性与重要变化

发布摘要

样式与定制：
- 导航栏改进，包括可配置浅色/深色主题与可调整高度；
- 标题别名与页内目标；
- 重新组织内部 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 告警语法：

Hugo 0.152.0–0.155.x 升级指南

Mon, 09 Feb 2026 00:00:00 +0000

本文总结 Hugo 0.152.0 至 0.155.3 的破坏性变更与重要变化，是 Docsy 0.14.0 与 0.13.0 发布和升级指南的配套文章。

升级摘要

本指南重点说明 Hugo 0.152.0–0.155.x 的破坏性变更，以及可能需要执行的操作。

审阅 BREAKING 变更：
- YAML yes/no Token 变为字符串
- 多维站点的构建顺序发生变化
审阅 弃用项（不具破坏性，但建议处理）：
- Mount 的 lang 选项已弃用
- includeFiles/excludeFiles 已弃用
可以快速浏览：
- 已知问题与修复
- 重要变化
准备好后，直接阅读升级到 Hugo 0.155.x

YAML yes/no Token 变为字符串（0.152.0）

0.152.0（2025-10-21）升级到更现代的 YAML 库，导致配置文件和页面 Front Matter 中某些 Token 的解释方式发生破坏性变化。

0.13.0 发布报告与升级指南

Mon, 24 Nov 2025 00:00:00 +0000

亮点

Docsy 0.13.0 包含 2025 年得票最高的功能请求，以及更多改进。
本版带来新功能，而且只有少量破坏性变更。¹
阅读我们使用 AI 升级 Docsy 项目的实践经验。

发布摘要

Docsy 0.13.0 包含以下重要功能与修复：

导航与用户体验改进，包括 2025 年 得票最高 的功能请求：目录活动项跟踪（#349、#2289）；
重写告警短代码，更好地支持 Markdown；
改进无障碍能力，增强颜色对比度和深色模式支持。

准备升级？

审阅 BREAKING 变更：
- 告警短代码正文处理方式变化；
- 语言菜单可见性变化。
可以快速浏览：
- 新功能；
- 其他重要变更。
准备好后，直接阅读升级到 0.13.0。

目录活动项跟踪

Docsy 0.13.0 引入 目录（TOC）活动项跟踪，这是 2025 年 得票最高 的功能请求。当读者滚动页面时，当前可见分区对应的目录项会高亮。该功能通过 Bootstrap ScrollSpy 的补丁版本实现。新增的默认目录标签“本页内容”与“返回页首”可以本地化。详情参阅使用 ScrollSpy 跟踪目录活动项。

从 Docsy 0.11.0 升级到 0.12.0

Tue, 11 Nov 2025 00:00:00 +0000

我们没有为 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¹

说明

本文覆盖最常见的升级步骤。项目定制项可能还需要额外调整。建议在 独立分支 中完成这些变更，并在部署到生产环境前进行 全面测试。

流程概览

更新 Docsy、Hugo 及其他依赖

1. 更新 Node.js

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

nvm install --lts

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

升级 on OINK 文档主题

0.16.0 发布报告与升级指南

发布摘要

准备升级？

/ 移动主题目录

Hugo 0.158.0–0.164.x 升级指南

升级摘要

语言 API 弃用项（0.158.0）

0.15.0 发布报告与升级指南

发布摘要

准备升级？

智能体支持

0.14.0 发布报告与升级指南

发布摘要

准备升级？

Markdown 告警语法

Hugo 0.152.0–0.155.x 升级指南

升级摘要

YAML yes/no Token 变为字符串（0.152.0）

0.13.0 发布报告与升级指南

发布摘要

准备升级？

导航与用户体验改进

目录活动项跟踪

从 Docsy 0.11.0 升级到 0.12.0

流程概览

更新 Docsy、Hugo 及其他依赖

1. 更新 Node.js