这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

博客

版本说明、升级指南与 OINK 工程实践

OINK 实施日记：从复制外壳到统一主题

记录 OINK 实现预览背后的技术决策、迁移方法、安全边界、测试与文档工作。
撰文： OINK 维护者 |

OINK 始于一个令人不安的事实：多个生产文档站之所以看起来相互关联，是因为它们确实源于同一套实现；但公共实现却以复制文件的形式散落在各处。呈现效果足够一致，维护模型却并非如此。

这篇日记记录项目如何从重复站点覆盖项走向一款直接演化的统一主题。它关注决策与证据，而不是逐条复述提交历史。

锁定产品契约

第一项真正有价值的工作是做减法。选择实现方式之前，我们先写清产品必须是什么：

  • 从 Docsy 直接演化而来的独立主题；
  • 唯一标准外壳，而不是可切换皮肤；
  • Hugo Extended 是消费端唯一构建依赖；
  • 所有主题自带浏览器资源默认本地优先；
  • 多语言行为从 Hugo 推导，而不是从 PGSTY 域名推导；
  • 可复用组件进入主题，业务语义留在站点；
  • 保留 Docsy 历史、许可证与可追踪的上游关系。

这排除了一个看似诱人、实际代价高昂的捷径：增加 params.oink.enabled 并保留旧外壳。模式开关会让每次布局调整、无障碍修复与测试都支持两套产品。直接演化则让目标设计成为唯一设计。

替换页面外壳

文档、博客与 API 参考布局围绕一组小型共享 partial 重新构建。新的外壳包括：

  • 全局导航与响应式次级导航；
  • 可调整宽度、可折叠的侧栏；
  • 本地搜索与快捷链接；
  • 语言与颜色模式控件；
  • 面包屑、目录（TOC）、页面元数据与反馈；
  • 一致的页脚与打印布局。

真正困难的不是画出导航栏，而是在删除复制的 baseof.html 时保留 Docsy 既有扩展点。范围明确的 hook 仍然存在；复制整个站点外壳不再是正常的定制路径。

移除消费端工具链

原有依赖链假设 Bootstrap 与 Font Awesome 来自 npm，部分路径还会调用 PostCSS。OINK 把必需源码与编译产物移入主题，并让 SCSS 留在 Hugo 自身的 Asset Pipeline 中。

测试不只检查 hugo 是否成功。fixture 中的陷阱会在消费端构建尝试运行 Node.js、npm、PostCSS 或 Autoprefixer，或模板调用 resources.GetRemote 时立即失败。LTR 与 RTL 页面遵守同一约束。

这里的区分非常重要：仓库仍使用 Node 运行维护者测试工具。“仅依赖 Hugo”描述的是消费站点取得完整主题后所需的构建环境，并不是禁止主题仓库使用开发工具。

纳管浏览器运行时

下一层工作覆盖浏览器原本可能从远端获取的全部依赖：Bootstrap、Font Awesome、字体、jQuery、Lunr、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic 及其辅助库。

theme/VENDOR.json 为每项选定产物记录来源、固定版本、许可证路径、校验值与更新流程。许可证与 vendor 内容相邻存放。清单会与真实文件一起验证，而不是停留在愿望列表。

PlantUML 与 Diagrams.net 迫使我们做出一项重要区分：它们依赖服务，而不只是 JavaScript 库。OINK 拒绝虚构公共端点；启用功能却没有配置服务时，构建会失败。

构建多语言内核

旧的语言行为散落在导航逻辑与站点专用假设中。新的内核从 Hugo 已配置语言、.Translations 与 .AllTranslations 出发。

呈现方式刻意保持稳定：只有一种语言时隐藏选择器；两种或更多语言统一使用同一个图标按钮。点击会按配置权重切换，短暂悬停或键盘聚焦则打开完整语言菜单。

缺少译文时回退到目标语言首页。语言名称使用该语言的自称。同一组对象还会驱动 lang、书写方向、canonical、 hreflang 与 Open Graph locale 元数据，因此可见选择器不会与 SEO 输出漂移。

测试会让 RTL 语言作为当前语言覆盖每种状态，而不只验证 starter 的两种 LTR 语言。原生链接与 disclosure 控件让键盘行为保持可预期。

提炼通用组件

Asciinema、ECharts、Infographic、文档轮播、折叠块、标签页、卡片与参数渲染，已经在 PGSTY 站点证明了价值。接下来的工作，是把复制品转化为产品 API：

  • 统一参数名称与默认值；
  • 根据页面身份与短代码序号生成唯一 ID；
  • 每页只加载一次运行时，未使用页面完全省略；
  • 保持子路径 URL 正确；
  • 支持多个内容完全相同的实例；
  • 提供打印、深色模式、移动端、键盘与减少动态效果行为；
  • 为导入内容保留兼容别名。

产品矩阵等业务控件没有迁入主题。是否复用不能只看有多少仓库包含同一个副本；通用组件必须拥有稳定、与业务无关的契约。

设计安全的 ECharts

ECharts 暴露了最尖锐的迁移边界。部分现有页面会在图表块中放置任意 JavaScript 函数。完全保留会让可执行内容成为默认 API；立即禁止又会破坏已经验证的生产页面。

最终方案把两种模式分开：

  1. 新内容提供 JSON 或 YAML，由 Hugo 解析并安全序列化；
  2. 默认拒绝 JavaScript；
  3. 经过审查的旧实例可以设置 unsafe=true；
  4. 站点级 params.content.echarts_unsafe 只作为迁移桥梁。

测试包含 </script> 边界载荷、内容相同的重复图表、非法 CSS 长度，以及明确的接受与拒绝场景。

创建 starter 与归档

如果最小示例能完整演示契约，契约就更容易获得信任。starter 包含双语首页、文档、博客与组件页面，以及本地搜索、深色模式、图表、API 文档和新增组件；它没有 package.json，也没有站点工作流。

离线打包器会组合 theme/、starter/、许可证、上游记录与迁移指南，并排除生成结果与依赖缓存。它会写出配套 SHA-256 文件，并拒绝覆盖已有产物。

验收测试把 starter 与主题复制到临时目录，清空缓存，阻断 HTTP/HTTPS 与 Go 代理，使用 Hugo 构建，再检查 HTML 与 CSS 中是否出现第三方子资源。

演练四站迁移

SILO、PGSTY、SOW 与 Pigsty 提供了现实检验。演练工具会复制各工作区而不是修改源目录，只删除已经分类的公共覆盖项，应用本地主题 replacement，禁止网络与前端工具，再运行生产构建。

最近一次演练分别从 SILO、PGSTY、SOW 删除 20 个公共覆盖项，从 Pigsty 删除 24 个。Pigsty 保留三个业务矩阵短代码，并使用显式的旧 ECharts 迁移桥梁。所有临时副本均成功构建，分别生成 1,095、16、128 与 2,473 个 HTML 文件。

这些数字证明的是记录提交上的迁移演练，不代表任何生产仓库已经改变，也不代表任何托管站点已经部署。

把样例站变成 OINK 文档

继承而来的 docsy.dev 站点是很有价值的回归语料库，但它只描述 Docsy。文档阶段完成了四项工作：

  1. 把英文设为首要语言、简体中文设为第二语言；后续外壳评审又从演示站点移除了法文；
  2. 为每份核心文档与博客源文件创建并置的 .zh.md 译文；
  3. 在每个中文标题中显式保留英文标题 ID；
  4. 增加 OINK 产品指南、项目公告与本实施日记。

翻译之前，我们先建立术语与排版指南。随后使用检查器验证源文件与译文配对、标题数量、中文显式 ID，以及渲染后的中英文标题 ID 是否完全相同。

Docsy 历史发布文章保持忠实翻译，其中的 npm 时代说明属于历史语境；OINK 架构与迁移指南则明确说明当前仅依赖 Hugo 的产品契约。

测试如何改变设计

多项测试不仅验证实现，也反过来改变了设计：

  • 子路径 fixture 迫使每个本地组件 URL 都经过 Hugo URL 处理；
  • 重复实例测试用“页面加序号”ID 替代内容哈希；
  • 离线浏览器检查暴露了隐含运行时请求；
  • RTL 语言矩阵避免选择器只适用于 starter 的两种 LTR 语言；
  • ECharts unsafe 拒绝测试把安全边界变成可执行契约；
  • 迁移演练保留了直接清空 layouts/ 时会被误删的站点专用 partial。

最有力的测试套件约束的是产品边界，而不只是当前 HTML 快照。

后续工作

目前仍有两个发布关卡有意保持开放。公开品牌、仓库、模块与软件包身份，以及首个版本需要批准。随后还要让真实 Cloudflare Pages 项目从源分支构建，并通过托管验证。

生产迁移应逐站进行，使用专用分支、预览部署、视觉回归与回滚产物。四站临时演练是这项工作的基础，不能替代正式迁移。

经验总结

  • 移动文件前先写清产品边界。
  • 本地优先承诺必须同时具有构建阶段与浏览器阶段证据。
  • 配置应表达用户选择，而不是内部实现分支。
  • 翻译质量不仅是正文，还包括稳定链接、代码保真、排版与渲染结构。
  • 复用应消除维护副本，而不能吞并业务语义。
  • “构建”“打包”“公开发布”“部署”与“迁移”是不同声明，需要不同证据。

最终成果没有重写那样戏剧化，却更加实用：一款能够作为完整产品被理解、构建、测试、翻译与迁移的统一主题。

OINK 实现预览正式亮相

OINK 将直接定制的 Docsy 代码库演化为本地优先、仅依赖 Hugo 的文档主题，并提供多语言基础设施与可复用内容组件。
撰文： OINK 维护者 |

今天，我们发布 OINK 实现预览：它从 Docsy 直接演化而来，提供唯一标准产品外壳、仅依赖 Hugo 的消费端构建、本地优先浏览器依赖、通用多语言框架，以及一组从 PGSTY 文档站提炼出的可复用内容组件。

这是实现与文档里程碑，不是已经公开的版本化发行。最终公开品牌、模块与软件包身份、首个版本，以及生产 Cloudflare Pages 部署，仍是必须显式关闭的发布关卡。

为什么需要 OINK？

多个成熟文档站分别复制了相同的 Docsy 布局、导航、搜索代码、SCSS、JavaScript 与短代码。一个公共修复必须在多个仓库重复实施；与此同时，每个站点都携带前端工具链与隐含网络依赖，让网络隔离构建变得异常复杂。

OINK 将真正可复用的部分合并到主题中。产品矩阵、门户、价格页和其他业务专用行为仍留在各自站点；共享主题负责文档外壳、浏览器运行时、多语言路由、无障碍行为与内容组件契约。

有哪些变化？

产品本身，而不是一种模式

OINK 不是可选皮肤。项目没有 oink.enabled 开关、params.oink.* 命名空间，也没有“上游版与品牌版”并行的模板树。theme/ 中的实现就是产品。

这项决策避免维护两套视觉系统与两套测试矩阵。Hugo 原生设置与兼容的 Docsy 参数继续保持原有含义。

消费端仅依赖 Hugo 构建

完整消费站点只需运行：

hugo --gc --minify

Bootstrap、Font Awesome、字体、搜索、图表、API 文档运行时与 OINK 组件都已随主题提交。Node.js、npm、PostCSS、Autoprefixer 与 CDN 下载不属于消费端要求。

仓库维护者仍会使用 Node 工具运行测试和更新 vendor 资源；这套维护工具链有意置于公开站点构建契约之外。

本地优先的浏览器行为

默认 starter 会从生成后的站点提供页面外壳、字体、图标、搜索、Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts 与 Infographic 依赖。可选运行时按页面选取，并且每页最多加载一次。

PlantUML 与 Diagrams.net 不再拥有公共服务默认值。站点必须配置受控端点、使用预渲染结果，或明确选择远程服务。

多语言基础设施

语言路由来自 Hugo 的语言与翻译对象。配置一种语言时隐藏选择器；配置两种或更多语言时，直接点击按配置顺序切换，短暂悬停或键盘聚焦则打开完整菜单。当前页面缺少译文时，选择器会进入目标语言首页，而不是失效路径。

starter 与本站均以英文为首要语言、简体中文为第二语言。核心文档与博客范围内的每个页面都有并置的 .zh.md 译文，且标题采用稳定的显式 ID。

可复用组件

OINK 新增主题级 Asciinema、ECharts、Infographic、文档轮播、折叠块、标签页、卡片、导航卡片、文档卡片与参数组件。它们会生成唯一实例 ID，并且只在实际使用时加载本地资源。

ECharts 默认接受结构化 JSON 或 YAML。旧 JavaScript 必须显式选择 unsafe 模式，让迁移例外始终可见、可移除。

哪些能力保持不变？

OINK 沿用 Docsy 的内容组织、front matter、文档与博客 section、菜单、taxonomy、打印输出、仓库链接、常用短代码、图表、API 参考能力与扩展 hook。现有站点可以删除重复公共实现，而不必重写普通 Markdown。

项目也保留 Docsy 的 Apache-2.0 历史与归属信息。vendor 清单记录固定的第三方来源、许可证、产物与校验值。

体验 starter

安装 Hugo Extended 0.160.1 或更高版本，然后在当前检出目录运行：

hugo --source starter --gc --minify

当前验证基线为 Hugo Extended 0.164.0。打开生成的英文与中文页面，切换语言、使用本地搜索、改变颜色模式，并访问组件示例。

需要传入网络隔离环境时，维护者可以创建完整归档：

scripts/package-offline.sh /absolute/path/oink-preview.tar.gz preview

归档包含主题、starter、许可证、上游记录、迁移指南、vendor 清单和配套校验值。

当前验证范围

当前实现的自动化覆盖包括：

  • 最低版本与当前版本 Hugo Extended 构建；
  • 禁止消费端 Node/npm/PostCSS/Autoprefixer 路径；
  • LTR、RTL、子路径、打印、颜色模式与生产资源；
  • 完整的一种/两种/三种/四种及以上语言选择器矩阵；
  • 本地按页运行时与重复组件实例；
  • ECharts 结构化数据与 unsafe 代码边界；
  • 离线双语 starter 与离线发行归档；
  • vendor 许可证与校验值；
  • SILO、PGSTY、SOW 与 Pigsty 的非破坏性迁移演练。

最近一次四站演练成功构建了临时副本，但没有修改或部署这些生产仓库。

正式发布前还需要什么？

公开身份与首个版本必须获批，并一致应用到模块、软件包、源码标签、嵌套主题标签、归档与文档。随后还要把目标 Cloudflare Pages 项目连接到源分支，使用固定 Hugo 版本构建、公开发布，并在托管 URL 上完成验证。

这些关卡关闭之前，请把该预览用于评估与迁移演练，不要把未固定版本的代码当作生产依赖。

0.16.0 发布报告与升级指南

Docsy 以 @docsy/theme 发布到 npm。本版还把主题移动到 theme/，提高 Hugo 最低版本，并删除默认 Favicon、改用自动发现；各项变更均附升级操作。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |
亮点

发布摘要

准备升级？

/ 移动主题目录

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

全新的 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操作，并注意：

使用 AI 升级？

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

基本检查

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

接下来是什么？

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

参考资料

关于本版：

  1. 与 docsy.dev 测试使用的 Hugo 锁定版本和主题声明的 Hugo 最低版本一致。更高版本的 Hugo 或 Node 可能可以工作，详见正式支持策略。 ↩︎

Hugo 0.158.0–0.164.x 升级指南

Docsy 站点从 Hugo 0.158.0 到 0.164.x 的变化：破坏性变更、弃用项、 安全修复与已知回归，以及各版本对应的升级操作。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

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

升级摘要

语言 API 弃用项（0.158.0）

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

Docsy 自身的模板和文档已经改用新名称——这也是 0.16.0 提高 Hugo 最低版本的原因之一。

操作

适用条件：多语言站点配置使用旧语言字段。请适时重命名，并检查语言菜单输出：

# OLD
languages:
  en:
    languageName: English
    languageDirection: ltr

# NEW
languages:
  en:
    label: English
    direction: ltr

适用条件：站点覆盖语言相关模板或 Partial。请在自定义模板代码中检查以下替换：

已弃用替代项
.Language.Lang.Language.Name
.Language.LanguageCode.Language.Locale
.Language.LanguageName.Language.Label
.Language.LanguageDirection.Language.Direction
.Site.LanguageCode.Site.Language.Locale
(Page|Site).Language.Weight没有直接替代项
跨站点语言使用 .Site.Languageshugo.Sites 或 .Sites

当前 Docsy 示例见多语言支持。

Markdown 链接转义（0.159.2，0.160.0 修复）

Hugo 0.159.2 包含一项针对 Markdown 链接和图片危险 URL 的安全修复，但也引入了回归：渲染后的 Markdown 链接 URL 中，& 可能被重复转义，在 HTML 输出中变为 &amp;amp;。

Hugo 0.160.0 修复了该回归，而 0.160.1 是更安全的 0.160.x 补丁版本。Docsy 0.16.0 的 Hugo 最低版本为 0.160.1，已经避开这一问题窗口。

操作

适用条件：曾短暂测试或部署 Hugo 0.159.2。请在生成的 HTML 链接 URL 中搜索 &amp;amp;。

模板与 Module 清理（0.159.x–0.160.x）

Hugo 0.159.x 延续了若干清理工作，旧 Docsy 站点、Docsy 分支或拥有本地模板覆盖的大型下游站点可能遇到这些问题。

操作

适用条件：站点有自定义模板、Module Mount 或转换脚本。

  • 用 hugo.Data 替代已弃用的 site.Data；
  • 用 files 替代已弃用的 Module Mount 选项 includeFiles 与 excludeFiles；
  • 用 :contentbasename 替代已弃用的永久链接占位符 :filename；
  • 如果运行 hugo mod npm pack，升级后进行测试；
  • 如果使用 hugo convert，提交前审阅生成输出。

适用条件：站点使用 Goldmark Passthrough、RenderShortcodes 或多语言根分区。Hugo 0.160.1 修复了此版本范围内与标题中的 Passthrough 元素、短代码渲染上下文标记和多语言根分区生成有关的回归；烟雾测试应覆盖这些页面。

Node 管理的工具（0.161.x）

Hugo 0.161.x 在 Node 的 --permission 沙箱中运行 PostCSS、Babel、Tailwind 等 Node 工具，因此要求 Node 22 或更高版本。

Docsy 站点通常使用 PostCSS 处理 CSS，所以即使 Docsy 主题本身没有变化，这也可能是实际破坏性变更。Hugo 0.163.2 与 0.163.3 修复了权限模型回归，PostCSS 流水线应优先使用 0.163.3 或更高版本。

操作

适用条件：站点使用 Hugo 0.161.x 或更高版本，并在 Hugo 构建期间运行 PostCSS、Babel、Tailwind 或类似 Node 工具。

  • 把 Node 升级到当前活跃 LTS；Docsy 0.16.0 使用 Node LTS 24；
  • 在本地构建并检查 Node 权限错误；
  • 如果 CI 把 node_modules 放在项目树之外——例如 Netlify 共享缓存——且构建以 ERR_ACCESS_DENIED 失败，请升级到 Hugo 0.163.2 或更高版本；
  • 如果 PostCSS 或 Babel 配置使用 .mjs/.cjs 变体，例如 postcss.config.mjs，请使用能够解析这些变体的 Hugo 0.163.3；
  • 使用 Tailwind 的项目应将 Tailwind 安装为 NPM 软件包；Hugo 不再支持这条路径中的独立 Tailwind 二进制文件；
  • Node 工具确实需要创建子进程，却被 Hugo 0.161.1 或更高版本拦截时，请审阅 security.node.permissions.AllowChildProcess。

内容与资源安全（0.161.x–0.163.x）

Hugo 在这一版本范围内收紧了多项安全边界：

  • security.http.urls 默认值更严格，resources.GetRemote 会重新检查重定向；
  • 除非通过 security.allowContent 允许，否则默认拒绝 text/html 内容文件；
  • 更多模板/资源函数会拒绝或忽略符号链接条目，包括 resources.Get，以及 0.163.1 中的 os.ReadDir、os.ReadFile、os.Stat 与 os.FileExists。

操作

适用条件：站点使用远程资源、手写 .html 内容文件、符号链接内容/资源，或在缓存 Partial 中使用 templates.Defer。

  • 使用目标 Hugo 版本在本地构建，审阅安全相关错误与警告；
  • 有意发布 .html 内容文件时，显式配置 security.allowContent；
  • 模板调用 resources.GetRemote 时，审阅 security.http.urls 并测试会发生重定向的 URL；
  • 内容或资源通过符号链接进入项目时，测试相关页面；如果 Hugo 拦截，应考虑改用 Hugo Mount 或真实文件；
  • 模板在 partialCached 内使用 templates.Defer 时，把延迟工作移到缓存 Partial 外部；Hugo 现在会报告这种无效组合，而不是静默产生错误结果。

图片处理弃用项与 URL 变动（0.163.x）

Hugo 0.163.0 弃用全局图片质量配置，改为按格式设置；同时新增 AVIF 相关配置，并修改内部缩放图片缓存键。

操作

适用条件：站点配置使用全局 imaging.quality 或 imaging.compression。

  • 改为按格式设置；如果取值与 Hugo 默认值相同，也可以直接删除；

  • 站点依赖 Docsy 风格的锐利照片缩小时，保留 resampleFilter: CatmullRom：

    imaging:
  resampleFilter: CatmullRom

图片 URL 变动

适用条件：站点提交生成输出、比较 Public 构建，或使用会积极缓存生成图片资源的 CDN。

在 Hugo 0.161.x–0.163.x 中，即使源图片与视觉输出不变，包含 _hu_<HASH> 的缩放图片文件名也可能变化。这是预期的缓存键变动，可能产生嘈杂 Diff 与缓存未命中，但通常并非内容回归。出现差异时，应检查实际渲染图片，而不只是文件名。

更快的构建与更严格的模板（0.164.0）

Hugo 0.164.0 修复了一项影响 0.128.0 至 0.163.x 的模板渲染性能下降。大型站点收益最明显：在一个约 8,500 页的 Docsy 站点报告中，完整构建时间从 608 秒降到 117 秒（见性能讨论）。

同一版本还收紧模板处理，并更新语法高亮：

  • resources.PostProcess 已弃用，请改用 templates.Defer；Docsy 模板没有使用 resources.PostProcess；
  • 指定的 View 模板缺失时，.Render 现在会令构建失败，而不是静默不输出；嵌套 View 名称恢复正常；
  • 内置 Chroma 会重新 Tokenize protobuf、YAML、Markdown 等语言：语法高亮 class 会变化，文本内容不变；
  • 多语言 Sitemap 中，每个 URL 的 xhtml:link 备用项现在优先列出该条目自身语言。

操作

适用条件：站点规模较大，覆盖或新增模板，或者提交生成输出。

  • 对干净的生产构建进行基准测试；模板密集型站点的构建时间可能大幅改善；
  • 在自定义模板中用 templates.Defer 替代 resources.PostProcess；
  • 修复所有引用缺失 View 模板的 .Render 调用；它们现在会令构建失败；
  • 把语法高亮 class 变化与 Sitemap 备用链接排序变化视为预期输出变动。

其他弃用项与重要变化

模板与配置弃用项

站点有自定义模板、外部内容转换器或 JavaScript 工具配置时，请审阅以下事项：

  • .IsNode 已弃用，请改用 .IsBranch；
  • 已删除 jsconfig 的 baseUrl 支持；
  • 如果从 Module Mount 页面读取 Git 元数据，请验证 .Page.GitInfo 输出。Hugo 0.162.0 修复了 go.mod 位于仓库子目录的 Module 的 GitInfo 处理；
  • 使用 --renderSegments 时，优先选择修复 Segment 合并的 Hugo 0.163.1；
  • 站点设置 uglyURLs: true，而且页面与分区同名——例如 download.htm 与 download/ 并存——时，请使用 Hugo 0.163.3，它修复了 0.163.x 早期引入的渲染冲突；
  • 通过外部转换器渲染 Pandoc 或 reStructuredText 内容时，Hugo 0.163.2 会在缺少转换器二进制文件时 令构建失败（与 AsciiDoc 一致），不再静默发布原始内容；所有构建环境都必须安装转换器。

安全修复

该版本范围包含多项安全更新，包括 Go html/template 修复，以及更严格的 URL/内容处理。Hugo 0.163.3 还加强了默认代码块渲染钩子：围栏代码块的语言 Token（Info String）现在会转义，这对渲染不可信 Markdown 的站点尤其重要。因此，与停留在 0.160.1 相比，更应优先使用 0.163.3 或更高版本。

值得了解的新功能

  • css.Build 以及后续 hugo:vars 支持可能有助于站点专属 CSS 流水线，但 Docsy 尚未把 Sass/PostCSS 流水线迁移到 css.Build；
  • 0.162.x–0.163.x 新增并持续调整 AVIF 图片处理；
  • Hugo 0.158.0 或更高版本为模板作者提供 strings.ReplacePairs；
  • Hugo 0.164.0 的 hugo gen chromastyles 新增 --mode 与 --modeSelector 参数，可以生成合并的浅色/深色语法高亮样式表。

升级到 Hugo 0.164.0

处理所有适用的破坏性变更与弃用项后，升级到 Hugo 0.164.0。

使用 hugo-extended NPM 软件包：

npm install --save-exact --save-dev hugo-extended@0.164.0

使用 hvm：

hvm use 0.164.0/extended

其他安装方式见安装 Hugo。

基本检查

确认已经处理适用于站点的每项操作，然后：

0.15.0 发布报告与升级指南

Docsy 0.15.0 发布报告与升级指南，涵盖智能体支持、文档根站点、版本菜单、 社区与 Footer 链接，以及卡片短代码渲染。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |
亮点

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

发布摘要

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

准备升级？

智能体支持

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

  • llms.txt；
  • 首页、分区和页面内容的 Markdown 备用输出；
  • 存在 Markdown 备用版本时显示 查看 Markdown 页面元数据链接。

如何为站点启用智能体支持及详细配置，见智能体支持。该功能为实验性。

智能体支持功能的分阶段演进见改进 AI 智能体文档消费支持 #2614。

文档根站点

Docsy 对 文档根站点 提供了新的改进支持，即把 docs 分区发布到站点根路径，而不是 /docs/ 下。这适用于以文档为主体、希望 URL 更短的站点，例如使用 /get-started/ 而不是 /docs/get-started/。

文档根站点也可以在站点根路径保留博客、社区等非文档分区。详情见文档根站点，也可以访问本站的文档根样例变体。该功能为实验性。

操作

适用条件：项目使用基于 Front Matter cascade 或 type 变更的旧版纯文档配置。

/ 版本菜单条目

Docsy 导航栏的版本菜单现在支持更丰富的条目处理：文字标题、分隔线、逐条页面链接行为，以及基于 Kind 的菜单项样式。配置详情见添加版本下拉菜单。

既有的简单 version 与 url 条目仍然有效。如果项目定制了版本菜单 Partial、CSS 或移动端导航栏布局，这项变更可能具有破坏性：菜单使用了更新后的标记与 class，而且在较小视口中不再隐藏。

操作

适用条件：项目配置 params.versions，并定制版本菜单或导航栏。

  • 审阅定位版本菜单下拉框的自定义 CSS；
  • 如果维护本地 layouts/_partials/navbar-version-selector.html 或 layouts/_partials/navbar.html 覆盖项，与 v0.15.0 导航栏 Partial进行 Diff；
  • 重新检查桌面端和移动端导航栏。

配置与样式详情见版本菜单和添加版本下拉菜单。

新增行为与修复：

  • Footer 链接支持 rel 属性，见添加社区页面（#2576）；
  • 社区与 Footer 链接现在只为外部链接打开新浏览器目标，修复 #2133（#2576）；
  • 站点内部的社区与 Footer 链接能在任意永久链接方案下正确解析（#2580）。

破坏性变更：

  • 在多语言站点中，链接路径现在按站点相对路径解释（#2580）。

适用条件：多语言站点在社区或 Footer 链接中配置站点内部路径。

  • 检查 params.links.user 与 params.links.developer 路径值，逐条判断目标应当是默认语言，还是当前站点（Locale）相对路径；

  • 如果路径应相对于当前站点，保持不变；

  • 如果路径应指向默认语言站点（即位于默认语言前缀下），请添加该前缀，例如用 /en/community/ 替代 /community/。

  • 在每种语言中重新检查生成的社区和 Footer 链接，确认目标站点正确。

/ 卡片短代码渲染

card 短代码一直支持在参数中使用 Markdown。现在，这些参数会在包含 card 的页面上下文中渲染，也就是说，参数值中的 Markdown 会在当前页面上下文解析，从而支持：

  • 在 card 参数 Markdown 中使用相对链接路径；
  • 在页面上下文中触发 Markdown 渲染钩子。

相对链接路径对多语言站点非常重要；在页面上下文中执行渲染钩子，也能提供更灵活的行为。

例如，下面的 card Footer 参数使用相对路径引用页面包图片资源：

{{< card
  header="**Imagine**" ...
  footer="![John's signature](card-pane/john-lennon-signature.png)"
>}}
...
{{< /card >}}

完整示例见card 短代码。

操作

适用条件：项目使用 card.html 短代码或维护自定义覆盖项。

  • 确认卡片渲染仍符合预期；
  • 如果希望使用新能力，更新站点的 card 覆盖项。

其他重要变更

国际化

变更摘要：

  • 新增或更新以下 Locale 的翻译文件：
    • 阿塞拜疆语：新增（#2082、#2604）；
    • 罗马尼亚语：新增（#2583、#2603）；
    • 德语：增加告警标签翻译（#2591）。
  • 为新增的“查看 Markdown”标签补充基础翻译（#2602）。

升级到 0.15.0

使用 AI 升级？0.15.0 附带实验性的机器可读升级清单，其中包含升级检测规则、适用条件、基本检查和逐项参考资料。可以把本发布报告与清单一起作为 AI 助手的上下文。

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

基本检查

接下来是什么？

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

参考资料

关于本版：

  1. 与 docsy.dev 声明的 params.hugoMinVersion 和 hugo-extended 一致。更高版本的 Hugo 或 Node 可能可以工作，但不在正式支持范围内。 ↩︎

0.14.0 发布报告与升级指南

Docsy 0.14.0 发布报告与升级指南，涵盖 Markdown 告警语法、导航栏样式改进、 标题别名与页内目标，以及项目与内部 SCSS 文件的进一步分离。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |
亮点

发布摘要

准备升级？

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

导航栏 高度与样式 可通过以下变量调整（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 外观，参阅项目样式，其中涵盖：

操作：必需与可选

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

移入 td/ 子目录的内部 assets/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 可能无法正确渲染。

  • 建议多数项目采用。3 如果希望 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）。

操作：必需与可选

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。本次升级版本如下：4

检查

基本检查

升级后，请检查：

同时审阅 0.12.0 的测试清单。

交叉检查

确认所有破坏性变更均已处理。下面汇总每节的必需与可选操作。

必需操作（如适用）

清理与站点改进（可选）

如果项目覆盖 Docsy 样式——导航栏、Block、目录等——请对照本版变化审阅覆盖项。这通常可以删除自定义 CSS/SCSS，减少技术债务。

界面与体验抽查（可选）

以下快速检查对应 0.14.0 的样式与行为变更：

  • 导航栏主题、高度与首屏半透明效果符合预期；
  • 片段链接和页内目标落在固定导航下方（见标题别名与页内目标）；
  • 内容页 <details> 间距正确；
  • 右侧栏目录 h1 粗细与对比度正确；
  • 使用 td/code-dark 时，浅色与深色模式中的代码块样式符合预期；
  • 控制台复制代码按预期只复制命令，不含输出；
  • 启用实验性额外样式时，检查导航链接装饰与嵌套列表间距。

高级审阅

适用条件：项目覆盖 Docsy 模板、短代码、资源或 i18n 文件。

审阅以下更新文件，并按需移植变更：

接下来是什么？

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

目标与反馈

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

参考资料

关于本版：

其他参考资料：

  1. 0.14.0 之前，导航栏背景使用主色。 ↩︎

  2. 除 Swagger UI 样式定制外，这不是破坏性变更，因为只涉及内部文件。 ↩︎

  3. 我们预计 td-below-navbar 对多数项目都是更合适的设计，未来版本可能将其设为默认值。 ↩︎

  4. 以上是对应 Docsy 版本正式支持的 Node.js 与 Hugo 版本。更高版本可能可以工作，但不在正式支持范围内。 ↩︎

Hugo 0.152.0–0.155.x 升级指南

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

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

升级摘要

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

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

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

过去，未加引号的 yes、no、on、off 等 Token 会被视为布尔值；现在它们会被视为字符串。完整 Token 列表见 0.152.0 发布说明。

操作：必需与可选

  • 适用条件：项目 YAML 中存在未加引号的 yes、no、on、off 等 Token。请把它们改为 true 或 false。

    搜索以下未加引号的键或值：

    • yes、Yes、YES、y、Y、on、On、ON：改为 true；
    • no、No、NO、n、N、off、Off、OFF：改为 false。

    示例：

    # OLD (now broken in 0.152.0+)
enabled: yes
disabled: no

# NEW (correct)
enabled: true
disabled: false

  • 适用条件：项目有自定义页面反馈配置。现在可以删除包含 yes、no 等 Token 的键（或值）外层引号。

    # OLD
params:
  ui:
    feedback:
      enable: true
      'yes': Glad to hear it! ...
      'no': Sorry to hear that. ...

# NEW
params:
  ui:
    feedback:
      enable: true
      yes: Glad to hear it! ...
      no: Sorry to hear that. ...

多维内容模型（0.153.0）

0.153.0（2025-12-19）引入了强大的多维内容模型。借助新的 sites.matrix 配置，除原有语言维度外，还能按版本和角色组织站点。

下面总结与多维站点相关的破坏性变更和弃用项。

多维站点的构建顺序

Hugo 现在根据排序后的维度构建站点——先按权重，再按名称——而不再从默认内容语言开始。.Site.Sites 的排序也会受到影响。

操作：必需与可选

适用条件：项目依赖特定的站点构建顺序，或按位置索引 .Site.Sites，例如通过下标访问。请改为显式选择默认站点。

具体修复取决于访问站点的方式。例如，代码包含 index site.Sites 0 时，应替换为 site.Sites.Default。更多实际示例见 open-telemetry/opentelemetry.io#8850。

弃用项

Mount 的 lang 选项已弃用

操作（建议）

适用条件：Mount 使用 lang。请切换到 sites.matrix，以消除弃用警告。

示例：

# OLD (deprecated)
- source: content/fr
  target: content
  lang: fr

# NEW
- source: content/fr
  target: content
  sites:
    matrix:
      languages: ['fr']

实际示例见 open-telemetry/opentelemetry.io#9070。

includeFiles/excludeFiles 已弃用

Mount 的 includeFiles/excludeFiles 选项已经弃用，请改用支持取反的 files Filter。

操作（建议）

适用条件：Mount 使用 includeFiles 或 excludeFiles。请切换到 files，以消除弃用警告。

示例：

# OLD (deprecated)
- source: content
  target: content
  excludeFiles: ['drafts/**']

# NEW
- source: content
  target: content
  files: ['! drafts/**']

实际示例见 open-telemetry/opentelemetry.io#9070。

已知问题与修复

0.153.x 中的别名处理

别名的已知问题

Hugo 0.153.x 的别名处理出现回归，至少影响了一个 Docsy 站点（docsy.dev）：

  • 默认语言别名：行为变化可能导致刷新页面异常，见 gohugoio/hugo#14363 与 gohugoio/hugo#14361；
  • 页面别名：在部分配置中可能指向错误语言，见 Docsy #2433。别名处理改进已经在 0.154.0 和 0.155.0 中修复此问题。

重要变化

以下重要变化不具破坏性。

0.155.0

  • Sites Matrix 支持版本与维度范围查询，例如 >= v1.0.0；
  • 页面别名可以在多维站点中正确工作；
  • 新增 XMP 与 IPTC 图片元数据支持。

0.154.0–0.154.5

  • 引入 Partial Decorator（inner 关键字），提供强大的模板组合能力；
  • 新增 Page.OutputFormats.Canonical 方法（0.154.4）；
  • 新增 reflect.* 函数，例如 reflect.IsPage；
  • 修复多维/多主机环境中的关键别名与站点重定向问题。

0.153.0

  • WebP 编解码改为通过 WASM 使用 libwebp，处理 WebP 不再需要 Extended 版本；
  • 支持动态 WebP，包括与动态 GIF 相互转换；
  • GoogleAnalytics.RespectDoNotTrack 默认值改为 true；
  • 删除重复内容路径警告，输出更安静，但也可能隐藏问题；
  • macOS 发行包 现在只提供经过签名与公证的 .pkg 安装程序，不再支持 .tar.gz。详见下方说明。

升级到 Hugo 0.155.x

处理所有破坏性变更和弃用项后，升级到 Hugo 0.155.x 的最新版本。使用 hugo-extended NPM 软件包时，可以运行：

npm install hugo-extended@latest

使用 hvm 管理 Hugo 版本时，可以运行：

hvm use latest

基本检查

把项目升级到 Hugo 0.155.x 后，请检查：

  • 构建输出：站点构建没有错误、警告与弃用通知；
  • 别名：默认语言重定向正确，页面别名指向正确的语言版本（见 0.153.x 中的别名处理）；
  • Sites Matrix 构建顺序：使用多维站点时，确认构建顺序假设依然成立（见多维站点的构建顺序）。

交叉检查

确认所有破坏性变更都已处理。下面汇总各节的必需与可选操作。

必需操作（如适用）

可选审阅

建议的最低 Hugo 版本

使用新 Sites Matrix 功能，而且希望获得多维站点中最新别名修复与支持的项目，建议使用 Hugo 0.157.0 或更高版本：

module:
  hugoVersion:
    min: '0.157.0'

0.13.0 发布报告与升级指南

Docsy 0.13.0 发布报告与升级指南，涵盖目录活动项跟踪、告警短代码改进、 无障碍增强和分区侧边栏根节点。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |
亮点

发布摘要

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

准备升级？

目录活动项跟踪

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

分区侧边栏根节点

Docsy 0.13.0 引入 sidebar_root_for 配置项，可以把侧边栏导航限制到指定分区。这对需要为不同分区采用不同导航树的大型站点尤其有用，也适用于同时包含非文档分区的纯文档站点。

在页面 Front Matter 中添加 sidebar_root_for 即可启用。支持 children 与 self 两种取值。用法与示例参阅分区侧边栏根节点，实现细节见 #2328 和 PR #2364。

语言菜单可见性

在 Docsy 0.13.0 之前，多语言站点的语言选择菜单会根据视口宽度，在导航栏与侧边栏之间切换：

位置宽视口窄视口
导航栏可见隐藏
侧边栏隐藏可见

可见性由 Bootstrap lg 断点触发，也就是宽窄布局切换的位置。

0.13.0 在所有视口宽度下的新行为如下：

位置所有视口宽度
导航栏可见
侧边栏隐藏

这是一项 BREAKING 用户体验变更。可以通过以下方式恢复旧行为：

  • 导航栏：把以下 SCSS（或等效样式）加入项目样式，恢复过去的 d-none d-lg-block 行为：

    .td-navbar__lang-menu {
  @extend .d-none;
  @extend .d-lg-block;
}

  • 侧边栏：在站点配置中把可选参数 .ui.sidebar_lang_menu 设为 true。

语言菜单详情见添加语言菜单；实现细节见 #2035、#2001 与 PR #2303。

移动端导航栏滚动提示

导航菜单发生溢出时——主要是在窄视口——导航栏现在会显示左右滚动提示，帮助用户发现更多导航项（#2406）。

告警短代码改进

从 Docsy 0.13.0 起，以 Markdown 形式（{{% alert %}}）调用 alert 时，正文采用新的处理方式：内部 Markdown 直接传给页面 Markdown 渲染器，与页面其余内容一起处理。此前，短代码会在内部调用 Hugo 的 markdownify 函数。

因此，告警现在可以：

  • 调用其他短代码，也就是 嵌套短代码；
  • 包含页面其他位置定义的链接，或与其他位置 共享链接定义；
  • 用在列表等 缩进上下文 中；
  • 包含会进入页面目录的 标题（针对 docs 页面）。

详情、示例和重要格式要求见 alert，实现细节见 PR #941。

需要操作：如果 .html 内容文件中使用 alert，而且正文含有 Markdown，则需要调整。

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

基本检查：抽查包含 alert 的页面，无论它位于 Markdown 还是 HTML 内容文件中，都要确认渲染符合预期。

无障碍改进

  • 主题整体的 颜色对比度 得到改善，Docsy 现在会回退到 Bootstrap 的字体与颜色默认值，从而提供更好的开箱即用无障碍合规性。详情见 #2285 和站点颜色。

  • 深色模式的 颜色对比度 改进：

    • 修复用户偏好与系统设置不同时的目录项颜色对比度（#2379）；
    • 为使用 Bootstrap 主题变量的项目提供早期实验性支持，允许定制对比度调整（#2384）。详情见选择具有良好对比度的颜色。EXPERIMENTAL

  • 深色模式：

其他重要变更

  • 更好的 NPM 支持：通过 NPM 使用 Docsy 的项目不再遇到 Optional 与 Peer Dependency 问题（#2115）。

  • 翻译（i18n）：新增奥克语 Locale（#2173），并更新简体中文（#2313）与乌克兰语（#2331）翻译文件。

  • 新增 _param 短代码：实验性参数替换短代码，适合生成动态模板内容。详情见 PR #2371。

  • 数学与化学公式：Docsy 改用 Hugo 内置 KaTeX 引擎在构建期渲染，mhchem 扩展也已内置。详情见使用 KaTeX 支持 LaTeX（#2276、#2394、#2395）。

    遇到公式时，KaTeX 引擎会自动启用，无需配置；项目可以删除已经过时的 params.katex.* 站点配置，包括 enable、html_dom_element、options 与 mhchem。

升级到 0.13.0

前提条件

我们建议 先阅读 Docsy 0.12.0 升级指南，因为该版本包含重要破坏性变更。

升级流程与 AI 辅助

你是否尝试过用 AI 协助升级 Docsy？它能帮上大忙！

0.12.0 升级指南同时面向项目维护者和 AI 助手编写。事实上，我已经用它成功升级 The Update Framework 等项目的网站。只以升级指南为输入，AI 助手就全自动创建了 TUF PR 126，而我只需要负责审阅。

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

升级后，请审阅破坏性变更，并全面测试站点。测试清单见升级到 Docsy 0.12.0指南。

接下来是什么？

2026 年已经规划了令人期待的增强功能3！

下一版暂定工作项与进度见 0.14.0 发布准备（#2404）。目前得票最高的增强请求包括：

参考资料

关于本版：

其他参考资料：

  1. 因此，本文不仅是一份升级指南，也是一份发布报告。 ↩︎

  2. 以上是对应 Docsy 版本正式支持的 Node.js 与 Hugo 版本。更高版本可能可以工作，但不在正式支持范围内。 ↩︎ ↩︎

  3. 有更多细节后，我们会在此发布，或更新 #2404。 ↩︎

从 Docsy 0.11.0 升级到 0.12.0

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

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

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

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

流程概览

  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：

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

  • 使用 Hugo Module：

    hugo mod get -u github.com/google/docsy@v0.12.0

  • 使用 Git Submodule：

    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 hugo-extended@0.147.5

4. 安装依赖

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

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

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

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

  • 将 _markup 上移一级：

    layouts/_default/_markup/  → layouts/_markup/

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

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

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

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

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

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

    # 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 标题模板：

    - {{ 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 或布局损坏；
  • 导航链接可解析，面包屑显示当前路径，当前分区正确高亮；
  • 移动端或平板上导航可用，关键页面没有横向滚动；
  • 外部链接显示预期样式，例如图标；
  • 标题自链接工作正常且样式正确；
  • 深色模式切换正常（如启用）；
  • 自定义短代码正确渲染（如使用）；
  • 搜索返回预期结果（如使用）；
  • 打印预览正确（如使用）。

参考资料

完整发布说明见：

其他参考资料：

  1. 以上是对应 Docsy 版本正式支持的 Node.js 与 Hugo 版本。更高版本可能可以工作，但不在正式支持范围内。 ↩︎ ↩︎

  2. 实现细节见 Issue #2243。 ↩︎

Docsy 2024 年回顾：采用与增强

回顾 Docsy 2024 年在功能与采用方面的增长：使用量提高 57%，新增深色模式， 并改进国际化支持。
撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

回顾 2024 年，我们很高兴看到项目稳步实现 2024 年工作重点中提出的目标。今年，我们专注于增强稳定性、改进国际化，并交付深色模式和持续集成（CI）测试等期待已久的功能。

2024 年，Docsy 的使用量从 1,400 个项目增长到 2,200 个，增幅达到 57%！1

下面一起回顾 2024 年的开发亮点，也展望一下后续计划。

版本亮点

今年我们发布了三个版本。每个版本都以稳定性为核心，同时至少引入一项重要功能增强：

  • 0.9.0 增加了几项 期待已久 的能力：
    • 通过 GitHub Actions 运行 CI 测试，保障 Linux 与 Windows 上的质量和可靠性；
    • Footer 定制——解决 Docsy 存在时间最长的 Issue（#2）！——同时改进仓库链接、无障碍能力与外观风格。
  • 0.10.0：
    • 升级到 Bootstrap 5.3，启用颜色主题和 深色模式，标志着 2021 年启动的 Bootstrap 5 迁移正式完成；同时调整短代码与样式，以兼容深色模式；
    • 处理核心 Hugo 升级到 0.123.0 带来的破坏性变更。
  • 0.11.0：
    • 利用 Bootstrap 的 RTL 能力重新引入 从右向左（RTL）语言支持，增强国际化。

主要功能增强

除了有助于提升 Docsy 稳定性的关键开发功能 CI 测试，2024 年还引入了以下主要用户功能。

深色模式支持

深色模式在 v0.10.0 亮相之前，是 Docsy 得票最高的功能请求。该功能以 Bootstrap 5.3 颜色主题为基础，并内置浅色/深色模式菜单选择器，便于项目启用。

我们计划在 Docsy 示例中启用深色模式，进一步降低采用成本。OpenTelemetry 等知名项目已经采用深色模式（opentelemetry.io#4023）。

从右向左（RTL）语言支持

RTL 语言支持（#1933）借助 Bootstrap 使用的成熟、经过充分检验的 RTLCSS 框架重新实现，取代了 Docsy 在 2023 年弃用的自定义 RTL 方案。

这项增强满足了多语言文档长期以来的需求。多个使用 Docsy 的大型站点都曾请求 RTL 支持，其中包括 CNCF 2024 年两个开发活跃度最高的项目：

项目采用与 Docsy Starter

Docsy 使用量持续增长，是 2024 年最令人振奋的进展之一。GitHub 分析数据显示，截至本文写作时，使用量 增长 57%，达到 2,200 个项目。

与 2023 年报告相比，CNCF 项目的采用量也有所增加。今年，Linux Foundation 导师项目学员 Sandra Dindi 与 Dariksha Ansari 使用 CNCF Docsy Starter，把以下站点迁移到 Docsy：

此外，Kubernetes 网站正在进行一次从 v0.2 起步的大规模 Docsy 升级，以对齐最新版本并减少技术债务：

升级进展顺利，可以查看正在推进的 0.3.x 升级和 0.5.x 升级。

未来展望

展望未来，我们很高兴能继续支持 gRPC（grpc.io#1389）与 Jaeger（jaegertracing#746）等项目升级和采用 Docsy。

2025 年首个版本暂定功能见 0.12.0 发布准备。目前得票最高的增强请求包括：2

感谢所有贡献者和用户，让 2024 年成为 Docsy 意义非凡的一年。祝大家在 2024 年末一切顺利，并以美好开局迎接 2025 年！让我们继续共同打造卓越的文档。

  1. 基于本文写作时 GitHub 分析页面中的 Docsy Dependents 数据。 ↩︎

  2. 请记得为最期待的功能投票。 ↩︎

Docsy 0.10.0 发布报告

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

Docsy 0.10.0 最大的新闻，是颜色主题与深色模式！

Hugo：破坏性变更与弃用通知

这个版本把 Docsy 的 Hugo 依赖从 0.122.0 升级到 0.125.4。需要特别注意：Hugo 0.123.0 是一次重大升级，包含若干 破坏性变更。升级到本版 Docsy 前，请审阅 Hugo 自 0.122.0 以来的弃用通知与破坏性变化。

本次发布的许多更新用于处理 Hugo 弃用通知。完整清单可在 0.10.0 版本变更中搜索标题含有“deprecat”的条目。

颜色主题与深色模式支持

本版最主要的功能，是通过升级到 Bootstrap 5.3（#1528）从 5.2 迁移到 5.3。这个 Bootstrap 次要版本引入了颜色模式，也称颜色主题。

作为升级验证，Docsy 新增了深色模式支持；在本版发布前，这是 Docsy 得票 最高 的功能请求（#331）。

如何为项目启用 浅色/深色模式下拉菜单，请参阅浅色/深色模式菜单。Docsy 用户指南已经启用该菜单；如果你正在在线阅读本文，不妨切换到深色模式试试看。

发布详情

本版完整变更清单——包括 Font Awesome、Mermaid、Algolia 与 KaTeX 更新——请查看 0.10.0 发布条目和 0.10.0 发布准备（#1759）。

接下来是什么？

Docsy 后续将有哪些改进？下一版暂定工作项见 0.11.0 发布准备（#1944）。

Docsy 0.9.0 发布报告

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

以 Docsy 的发布规模衡量，Docsy 0.9.0 是一次相当可观1的更新（包含 65 个以上 PR），其中有若干值得特别说明的破坏性和重要变更，主要涉及：

感谢所有贡献者！

本版全部 Footer 改进与修复见 #1818。本节选取其中几项介绍。为了让定制更加容易，我们还为下一个主要版本规划了更多 Footer 改进（#1852）。

为简化定制，Footer 布局被拆分为左、右、中三个部分（#1500），其中版权又是中间部分的子组件（#1817）。每一部分都有独立 class，例如 td-footer__left，便于定制样式。请注意，td-footer__copyright-etc 已重命名为 td-footer__center。

太好了！我们终于关闭了 Issue #2！

本版解决了 Docsy 存在时间最长、也是项目创建的第一个 Issue：

Footer 版权现在支持年份范围，并可以回退到站点版权配置：

  • Hugo 配置 params.copyright 过去只能是字符串，现在也可以是包含 authors、from_year、to_year 等可选字段的 Map。to_year 未设置时，默认为站点构建年份；authors 默认为“<Site.Title> Authors”，并按 Markdown 渲染；
  • params.copyright 未设置时，会使用站点 copyright 配置，并将其按 Markdown 原样渲染，不会附加日期。

  • About 页面链接默认隐藏。如需启用，请在项目配置中把 .params.ui.footer_about_enable 设为 true。.params.ui.footer_about_disable 已弃用；

  • “保留所有权利”文本默认隐藏。如需显示，请在 _styles_project.scss 项目样式文件中加入以下规则（必要时可添加 !important，示例未写）：

    .td-footer__all_rights_reserved {
  display: inline;
}

仓库链接及其他页面信息

从 2019 年起，如何正确生成仓库链接一直困扰着 Docsy 维护者与贡献者（#138）。难点在于，无论下游项目使用单语言还是多语言、是否设有首页，链接都必须正确工作。

最终，指导委员会成员 Lisa 的坚持取得了成果。Lisa 半开玩笑地说：我们只花了几年时间，又等来了几项 Hugo 改进。 确实，直到 2023 年 5 月发布的 Hugo 0.112.0 提供必要函数后，问题才得以解决。详情请参阅：

我们相信 Lisa 的修复已经彻底消灭仓库链接缺陷。

正如 CHANGELOG 所述，对于使用 Mount 且页面配置了 path_base_for_github_subdir 的站点，这是一项 破坏性变更。

从仓库/页面元数据链接修复与改进（#1841）可以看到，仍有若干问题尚待解决。不过，修复 #1744 已经为后续工作奠定必要基础。#1841 中列出的问题将在未来版本中通过进一步重构与扩展布局解决。

页面最后修改信息

可以配置站点，在文档和博客页底部显示页面源码的最后修改元数据。详情参阅用户指南新增的页面最后修改元数据一节。

外观与风格

Docsy 改为通过 Hugo render-heading.html 钩子在构建期生成标题自链接，取代由 assets/js/anchor.js 在客户端渲染的旧实现（该文件在 #1460 中删除）。项目现在必须显式启用此功能，详情见标题自链接。

默认自链接符号过去是嵌入式 SVG，现在改由 CSS 定义为网站常用的 #。项目可以通过 .td-heading-self-link class 定制外观。

标题自链接现在：

  • 在移动端和触控设备上始终可见；
  • 在其他设备和屏幕上，仍与过去一样，只在鼠标悬停到标题上时显示。

Docsy 现在遵循推荐的 无障碍实践：页面正文中的 链接默认带下划线。详情见 #1814 与 #1815。

再见，省略号

blocks/feature 短代码的“阅读更多”链接文本后不再自动附加省略号（“……”）。希望恢复省略号的项目，可以在站点各语言的 "ui_read_more" 语言参数中自行加入（#1820）。

持续集成测试

为保障 Docsy 的质量与稳定性，本版通过 GitHub Actions 引入了期待已久的开发者功能：持续集成（CI）测试。

每个 PR 以及主分支提交都会触发以下工作流：

  • 在 Linux 与 Windows 上运行跨平台测试；
  • 执行构建测试，确保 Docsy 及其用户指南成功构建，并通过链接校验等检查；
  • 从零构建 Docsy 站点的烟雾测试，同时验证 Docsy 作为 Hugo Module 与 NPM Module 的用法。

由于访问 Windows 环境的条件有限，Windows 支持采用尽力而为原则；即便如此，跨平台测试仍有助于更早发现潜在构建问题。

这项工作是提高主题可靠性的重要一步。未来我们计划扩大测试覆盖率（#726）。

参考资料与后续版本

本版完整变更清单见 0.9.0 发布条目以及 0.9.0 发布准备（#1759）。

Docsy 接下来会有哪些改进？下一版暂定工作项见 0.10.0 发布准备（#1812）。

0.10.0 及后续版本的功能和修复候选项，目前包括为重新引入 RTL 支持而继续推进 Bootstrap 工作，具体如下：

  1. 这里的“可观”以 Docsy 发布的一贯规模为参照。 ↩︎

Docsy 2024 年工作重点

撰文： Patrice Chalin（CNCF）， 代表 Docsy 指导委员会 |

摘要：已有 1,400 个项目使用 Docsy！2024 年面向使用方项目的首要任务，是提升 Docsy 的稳定性、易用性、可定制性与整体一致性，同时整合现有功能。

Hugo 与 Docsy 的组合强大而高效，我也曾在其他文章中介绍过。因而，看到 Docsy 已被 1,400 个项目使用1，或许并不令人意外。Docsy 为什么受欢迎？我无法给出确切答案，但我之所以使用并推荐它，是因为它具备发布成熟技术文档站所需的核心能力：版本管理、多语言、自动生成站点导航等。它上手迅速，让项目可以把精力放在内容交付上，而不是从头编写站点模板。

面向使用方项目与长期愿景

指导委员会成员（包括我本人）正在积极支持 CNCF 和 Google 内部多个依赖 Docsy 的项目。作为 Docsy 的使用者与贡献者，我们都与它的长期健康发展休戚相关。我们设想的工作重点如下：

  1. 通过缺陷修复和必要升级，保障 Docsy 核心功能的稳定性——例如从已经停止维护的 Bootstrap 4 迁移到版本 5；
  2. 减少 技术债务；
  3. 提升 易用性、可定制性与可维护性，尤其要更清晰地划分并记录“API 表面”，也就是配置与定制边界；
  4. 整合功能，下文将进一步解释。

Google 在五年多前将 Docsy 开源。得益于社区贡献，它的稳定性和功能集合不断增强；与此同时，Docsy 也积累了相当多的技术债务，而且在我看来已经出现轻微的软件膨胀与功能蔓延。因此，除了持续投入长期稳定性与可维护性，我们还需要 重新确认 Docsy 的核心功能，并降低其他功能的优先级2，以免遭遇与 cross-env 等项目类似的处境。可以把这理解为给 Docsy 做一次“功能瘦身”。

在推进 2024 年目标之前，我们计划先搭建 测试基础设施，并逐步扩充测试套件，以确保 Docsy 在演进过程中保持完整可靠。

结语

这对 2024 年乃至更长时间而言是一项艰巨任务，但我相信稳扎稳打终能取胜。

我们期待听到 Docsy 社区的声音！请分享你的看法，告诉我们应如何把握重点、改进 Docsy。可以查看按季度里程碑整理的 Issue，粗略了解后续版本的目标。请为你关心的议题投票或留言；我们会在既定优先级范围内尽力回应并调整发布目标。更进一步，也欢迎直接参与当季任务。新年开始后，我们尤其希望得到测试与功能整合方面的帮助。

  1. 数据来自 Docsy 的 GitHub 分析页面。 ↩︎

  2. 核心范围之外的功能甚至可以迁移到由社区维护的独立仓库。指导委员会也在考虑为部分次要功能设计“插件”架构，例如 Mermaid 支持。 ↩︎

升级到 Docsy 0.7 与 Bootstrap 5

结合实例说明如何升级到 Docsy 0.7 与 Bootstrap 5
撰文： Patrice Chalin（CNCF & Docsy 指导委员会） |

去年六月，Docsy 发布 0.7.0，迎来一项重要里程碑。这次重大升级源自历时六个月的细致工作（#470），核心任务是迁移到 Bootstrap 5.2。关于这段历程的亮点与缘由，请参阅迁移到 Bootstrap 5.2。

本文基于我升级 Docsy 0.7 的亲身经验，重点围绕 Bootstrap，帮助读者完成 Docsy 0.7 与 Bootstrap 5 升级。文章先为准备升级的 Docsy 项目提供通用建议。每个项目的迁移经历都不相同，但希望本文以及其中两个案例能让你的升级过程更轻松、更高效。

既然读到这里，你大概已经准备升级自己的 Docsy 项目——那就开始吧！

升级项目

正如上一篇文章所述，每个项目使用的 Bootstrap 与 Docsy 功能组合都不相同，因此 你的升级之路很可能独一无二。本节给出一些通用建议。

升级 Docsy

如果还没有这样做，请先把项目完整升级到 Docsy 0.6。每次 Docsy 发布都可能带来一组独立的升级挑战；实际规模与工作量取决于项目使用的功能，以及上一次升级距今有多久。先解决 0.7 之前的所有问题，才能专注于 Bootstrap 5。完成后，再升级到最新的 Docsy 0.7.x。

处理 Bootstrap 变更

建议先通读 Bootstrap 5.2 的迁移页面，了解相较 Bootstrap 4 的变化范围。找出项目实际使用功能中的破坏性变更，再逐项解决。下面列举其中几类，最后还会说明如何处理其余问题。

有些 Bootstrap 变更会明显破坏站点布局或功能，例如 ml-1、pr-2 等工具类重命名。可以在项目自定义布局或文档页的内联 HTML 中使用正则表达式批量搜索替换。我曾使用以下表达式：

  • 外边距与内边距：\b([mp])[lr](-([0-5]|auto))\b
  • 左/右相关类：\b((float|border|rounded|text)-)(left|right)\b

如果项目使用下拉菜单、Popover 或 Tooltip 等 Bootstrap JavaScript 插件，那么在调整数据属性名称前，这些功能都会停止工作。新属性统一使用 data-bs 前缀进行命名空间隔离，例如应使用 data-bs-toggle，而不是 data-toggle。

还有一些 Bootstrap 破坏性变更需要更多工作，例如上一篇文章摘要中提到的：

Docsy 博客布局曾使用 .media 类，而它已被 Bootstrap 5 删除。这项变化与 .row、.col 样式变更一起，导致博客布局经过数轮迭代，例如 PR #1566。如果项目覆盖了博客布局，就应仔细审阅这些更新；否则会自动获得相关变更，无需额外处理。

如果遇到本文没有提及、但会影响项目的 Bootstrap 5 破坏性变更，可以查看 Docsy Issue #470：升级到 Bootstrap 5.2的首条说明。其中列出 50 个任务，分别处理不同的迁移问题，并附有说明或交叉引用的 PR，展示每个问题的解决方式。

处理 Docsy 特有变更

这里也应简要说明 Docsy 0.7 中与 Bootstrap 无关的主要变化：

  • blocks/section 的 type 参数默认值与可接受取值发生变化（#1472）；
  • 不再支持 Hugo 0.54.x 之前的 {{% %}} 行为（#939）；
  • 要求 Hugo 0.110.0 或更高版本。

完整变更清单请查看 0.7.0 CHANGELOG。

案例研究

下面通过 OpenTelemetry 项目与 Docsy 示例模板仓库，展示 Docsy 升级过程。

opentelemetry.io

多个 CNCF 项目都使用 Docsy 主题，其中包括我用作 Docsy 预发布测试站的 opentelemetry.io。按照前述建议，我先把 Docsy 从 0.4 升级到 0.6（opentelemetry.io Issue #2419）。

升级到 Docsy 0.7 的过程相当顺利。除了工具类改名、数据属性命名空间等“显而易见”的变化，OTel 网站还需要完成以下项目专属调整：

  • 表单的破坏性变更要求大幅重做 Registry 表单；
  • OTel 网站虽然没有覆盖博客布局，却在 Registry 条目中使用了已删除的 .media 类，因此改用 Flex 样式。

仅此而已。两项问题的具体解决方式见 OTel PR #2490。

Docsy-example

docsy-example 是一个 GitHub 模板，我们通常建议准备用 Docsy 创建新站点的用户从这里起步。示例站支持多语言，这也影响了所需升级工作。

示例站升级甚至比 OTel 更简单。关键变更（PR #221）主要集中在各语言的落地页：

  • 工具类从 .ml-*、.mr-* 等改为 .ms-*、.me-*；
  • blocks/section 发生变化（PR #1472）：
    • 语言落地页需要从 .html 改名为 .md，以便使用块短代码渲染 Markdown；
    • 对表示行的 blocks/section 元素改用 type="row"（也见 PR #220）。

就这些。

下一步是什么？

如果项目没有覆盖任何 Docsy 布局，升级过程应该比较直接；反之，布局文件的每项变化都值得格外仔细地审查。

希望这些建议能让你的 Docsy 0.7 升级更顺畅。欢迎在 0.7.0 讨论或后续 0.7.x 版本下留言，分享自己的经验。祝升级顺利！

特别感谢 Erin McKean 对本文提出细致而宝贵的意见，也感谢所有参与 Docsy 0.7.x 系列版本的贡献者！

迁移到 Bootstrap 5.2

Docsy 从 Bootstrap 4 迁移到 5.2 的经验总结、技术洞察与操作建议。
撰文： Patrice Chalin（CNCF & Docsy 指导委员会） |

Docsy 以及使用 Docsy 的项目网站（包括 CNCF 项目）从一开始便一直愉快地采用 Bootstrap CSS 框架。今年一月，Docsy 过去几年使用的 Bootstrap 4 终止维护。Docsy 指导委员会一直期待 Bootstrap 5 带来的改进，却也担心迁移工作量及其对下游项目的影响，因此尽可能推迟了迁移。2022 年 12 月 Bootstrap 4 停止接收关键更新后，我们宣布 Docsy 进入功能冻结期，并把维护工作集中到 Bootstrap 5 迁移上。

本文记录 Docsy 迁移到 Bootstrap 5.21 的历程：重点介绍其中最值得关注的步骤，并特别分析最出人意料的部分。我们希望本文能帮助其他准备升级到 Bootstrap 5 的项目，尤其是 Docsy 下游项目——不过，我们还会另写一篇专门面向下游项目的文章。

摘要

准备直接投入项目的 Bootstrap 迁移？除了仔细通读 Bootstrap 迁移页面，还要特别留意：

  • media-breakpoint-down() Mixin 的断点参数需要上移；
  • 网格 .row 与 .col 样式变更具有破坏性；
  • Bootstrap Sass 文件的导入顺序：必须先导入函数。

下文将逐项说明。

技术细节

如果你习惯通过阅读 Changelog、逐项检查提交来升级 Docsy 及其依赖，本节可以作为若干重要变更的摘要。这里记录的技术问题之所以令我意外，是因为它们要么需要格外谨慎地修复，要么没有文档，或者在 Bootstrap 迁移页面中解释得不够充分。

media-breakpoint-down() Mixin 参数上移

传给 media-breakpoint-down() Mixin 的断点参数需要提升到下一个更高断点。值得庆幸的是，media-breakpoint-up() 不需要类似调整。Docsy 下游项目也必须完成这项变更。如果漏掉这个并不直观的破坏性布局变化，项目的响应式布局很可能以看似莫名其妙的方式失常。

详情与示例请参阅：

网格 .row 与 .col 样式变更具有破坏性

截至本文写作时，本节讨论的主要问题尚未出现在 Bootstrap 5 迁移页面中。

Bootstrap 5 似乎假定 .row 的直接子元素应当是 .col，但我并不确定这一假设究竟有多严格。我曾在 Bootstrap 文档中寻找明确表述，却没有找到——如果你知道出处，欢迎告诉我们。

这项假设在 Bootstrap 4 中并不明显，也没有被强制执行，因此 Docsy 的部分布局没有遵守它。多数情况下，只需用 .col 包裹 .row 的子元素即可修复；但 Docsy Footer 经过几轮迭代才正确适配。

我的第一版 Footer 调整把 flex-shrink 恢复为默认值（PR #1373）。后来，在更准确地理解如何处理 Row Margin 后（PR #1523），才发现这并无必要——我也是最近才知道，Row 使用负外边距，这一点值得牢记。

Bootstrap 5 对 .col 的以下样式变更影响了 Docsy 专属样式更新，也可能影响下游项目：

参考资料：

Bootstrap Sass 文件导入顺序：函数优先

项目既可以一次性导入全部 Bootstrap Sass 源码（使用 bootstrap.scss），也可以从 40 多个 Bootstrap Partial、布局与组件中按需导入。无论选择哪种策略，由于 Sass Map 初始化限制，使用 Bootstrap 的项目都必须做到（着重号为本文所加）：

……变量定制必须位于 @import "functions" 之后，但在 @import "variables" 及 [Bootstrap] 其余导入栈 之前。

详情请参阅迁移页面的新增 _maps.scss，以及 Bootstrap Sass 定制文档中的导入。

维护几十项自定义导入列表——哪怕列表相对稳定——也是本可避免的负担。因此，在 Docsy 的 main.scss 中，我们先导入 functions，再加载 Docsy 与项目变量覆盖，最后导入整套 Bootstrap SCSS。这样 _functions.scss 会被导入两次；不过根据 Sass @import 文档：

同一份样式表导入多次时，每次都会重新求值。如果其中只定义函数与 Mixin，通常问题不大；若包含样式规则，则会多次编译进 CSS。

_functions.scss 只包含函数定义，因此应该没有问题。与直接内联 bootstrap.scss 中 40 多项导入的策略相比，这点成本可以接受。

参考资料：

系统化、分步骤迁移

只要粗略看过 Bootstrap 5 迁移页面，就会发现需要处理的变化非常多。为了不漏掉任何一项，我们系统地逐段审阅迁移指南，并通过 Docsy Issue #470 跟踪每项变化的状态。Issue 首条说明对应迁移页面的各个章节：不适用于 Docsy 的会明确注明，其余则加入跟踪清单，并列出包含相应 Docsy 修改的 PR。若想了解最终过程，请查看升级到 Bootstrap 5.2 · Docsy Issue #470。

Docsy 的首个 Bootstrap 5 版本

迁移的大部分工作已经完成，因此我们计划在六月初发布首个基于 Bootstrap 5 的 Docsy 版本。部分更新被推迟，其中最显著的是从右向左（RTL）文字支持。完整后续事项请查看 BSv5.2 升级后续 · Docsy Issue #1510。

如前所述，首个版本将支持 Bootstrap 5.2。我们计划通过另一轮迁移把 Docsy 升级到 Bootstrap 5.3，尤其希望利用新版颜色模式。进度可在 Docsy Issue #1528 中跟踪。

迁移 Docsy 下游项目

本节先为下游项目提供初步、通用的建议。我们计划另写文章覆盖更多迁移细节。

通读 Bootstrap 迁移页面

每个项目使用的 Bootstrap 功能组合都不同，因此多数项目都应逐项检查 Bootstrap 5.2 迁移页面。当然，也可以直接升级，看看哪里损坏或失效；但除了最简单的项目，仅仅这样做而不进行系统复查并不可取——想想前文所述，漏改一个 media-breakpoint-down() 参数会多么难以发现和恢复。

Docsy 特有变更

迁移过程中，我们也借机完成了一些迟来的 Docsy 清理工作。Docsy 特有的破坏性与非破坏性变化详见 Changelog。尤其值得注意的一项非破坏性重要变化是：[BSv5] Docsy 变量清理……PR #1462。

动手试一试！

要快速获得升级对项目影响的第一印象，直接升级 Docsy 并观察哪里损坏往往很有帮助。Docsy 团队迁移 Bootstrap 5 时就是这样做的。真正令 Docsy 用户指南构建失败的只有一项变化：color-yiq() 函数重命名。

完成烟雾测试后，仍建议按照前述方式系统审阅 Bootstrap 迁移页面与 Docsy Changelog。我在 opentelemetry.io 上采用了这一方法；它是第一个升级到 Bootstrap 5 预发布版 Docsy 的下游项目。整个过程相当顺利。OTel 网站最大的难点是升级 Bootstrap 5 表单；Docsy 只使用最简单的表单，因此没有遇到这项问题。

我们会在后续博客文章中继续分享 OTel 迁移经验与项目专属建议。与此同时，希望这篇技术文章已经对你的迁移有所帮助。

急于迁移的 CNCF 项目网站可以在 CNCF #techdocs Slack 频道提问。CNCF 与其他 Docsy 项目也可以在 Docsy 仓库发起讨论。祝迁移顺利！

衷心感谢 Docsy 指导委员会和其他审阅者对早期草稿提出意见，也感谢所有参与迁移工作的贡献者。

本文另有一个版本首发于 CNCF 博客，题为将 Docsy 迁移到 Bootstrap 5。

  1. Bootstrap 5.3 已于 5 月 30 日正式发布。我们会通过独立的迁移工作将 Docsy 升级到 Bootstrap 5.3。 ↩︎

Docsy，你好！

欢迎来到 Docsy 博客！

你好

一个已经存在数年的项目突然发布“你好”文章，或许有些奇怪。不过，随着 Docsy 逐渐成长为社区驱动的项目，我们觉得是时候重新介绍自己，也聊聊大家喜爱的——至少我们希望如此——Hugo 文档主题最近有哪些新进展。

欢迎参与讨论

最近，我们的 Discussions 十分活跃！请不要错过关于即将弃用 Font Awesome 与 Bootstrap Git 子模块的通知，以及全新治理模式的公告。

里程碑、版本与路线图

我们计划很快发布 Docsy 的首个正式版本——可以查看 0.2.0 里程碑。对路线图有建议？欢迎提交 Issue。

即将推出：项目指标

从下个月开始，我们会在本博客发布项目指标。

PSC 正式成立

Docsy 现在拥有项目指导委员会（Project Steering Committee，PSC）！成员包括 @chalin、@LisaFC、@geriom 与 @emckean。如果你有兴趣加入 PSC，请提交 Issue 自荐。

为博客贡献内容

贡献指南也即将推出。有博客选题？欢迎提交 Issue！