去年六月，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 破坏性变更需要更多工作，例如上一篇文章摘要中提到的：

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

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 系列版本的贡献者！

• ←上一页
• 下一页→