博客 on OINK 文档主题

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

Sat, 08 Aug 2026 00:00:00 +0000

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 页面遵守同一约束。

OINK 实现预览正式亮相

Sat, 08 Aug 2026 00:00:00 +0000

今天，我们发布 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 依赖。可选运行时按页面选取，并且每页最多加载一次。

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）。

Docsy 2024 年回顾：采用与增强

Thu, 12 Dec 2024 00:00:00 +0000

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

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

下面一起回顾 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 0.10.0 发布报告

Wed, 01 May 2024 00:00:00 +0000

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

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

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

提醒

Docsy 及其对等软件包的正式支持范围见正式支持边界。

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

颜色主题与深色模式支持

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

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

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

重要样式变更

为兼容浅色和深色模式，以下短代码与页面元素的样式已经调整。

如果曾定制这些短代码和元素相关的 SCSS，就需要 重新检查项目样式。

alert（#1908）
card（#1922）
pageinfo（#1915）
标签页短代码（#1920）

搜索框样式与文档页左侧导航也已调整。

发布详情

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

Docsy 0.9.0 发布报告

Fri, 09 Feb 2024 00:00:00 +0000

以 Docsy 的发布规模衡量，Docsy 0.9.0 是一次相当可观¹的更新（包含 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 应支持更灵活的版权声明（#2），由 @sarahmaddox 提出。

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 已弃用；

Docsy 2024 年工作重点

Tue, 28 Nov 2023 00:00:00 +0000

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

Docsy 是广受欢迎的主题

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

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

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

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

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

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

结语

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

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

升级到 Docsy 0.7 与 Bootstrap 5

Thu, 03 Aug 2023 00:00:00 +0000

去年六月，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 5.2

Mon, 05 Jun 2023 00:00:00 +0000

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

本文记录 Docsy 迁移到 Bootstrap 5.2¹ 的历程：重点介绍其中最值得关注的步骤，并特别分析最出人意料的部分。我们希望本文能帮助其他准备升级到 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 下游项目也必须完成这项变更。如果漏掉这个并不直观的破坏性布局变化，项目的响应式布局很可能以看似莫名其妙的方式失常。

Docsy，你好！

Thu, 07 Apr 2022 00:00:00 +0000

你好

一个已经存在数年的项目突然发布“你好”文章，或许有些奇怪。不过，随着 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！

博客 on OINK 文档主题

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

锁定产品契约

替换页面外壳

移除消费端工具链

OINK 实现预览正式亮相

为什么需要 OINK？

有哪些变化？

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

消费端仅依赖 Hugo 构建

本地优先的浏览器行为

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

Docsy 2024 年回顾：采用与增强

版本亮点

主要功能增强

深色模式支持

Docsy 0.10.0 发布报告

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

颜色主题与深色模式支持

发布详情

Docsy 0.9.0 发布报告

Footer 改进

Footer 布局变更

Footer 版权年份范围及其他改进

精简 Footer

Docsy 2024 年工作重点

Docsy 是广受欢迎的主题

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

结语

升级到 Docsy 0.7 与 Bootstrap 5

升级项目

升级 Docsy

处理 Bootstrap 变更

迁移到 Bootstrap 5.2

摘要

技术细节

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

Docsy，你好！

你好

欢迎参与讨论

里程碑、版本与路线图

即将推出：项目指标

PSC 正式成立

为博客贡献内容

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