# 升级到 Docsy 0.7 与 Bootstrap 5 > 结合实例说明如何升级到 Docsy 0.7 与 Bootstrap 5 --- LLMS index: [llms.txt](/llms.txt) --- 去年六月，Docsy 发布 [0.7.0](https://github.com/google/docsy/releases/tag/v0.7.0)，迎来一项重要里程碑。这次重大升级源自[历时六个月的细致工作（#470）](https://github.com/google/docsy/issues/470)，核心任务是迁移到 Bootstrap 5.2。关于这段历程的亮点与缘由，请参阅[迁移到 Bootstrap 5.2](/zh/blog/2023/bootstrap-5-migration/)。 本文基于我升级 Docsy 0.7 的亲身经验，重点围绕 Bootstrap，帮助读者完成 Docsy 0.7 与 Bootstrap 5 升级。文章先为准备升级的 Docsy 项目提供通用建议。每个项目的迁移经历都不相同，但希望本文以及其中两个案例能让你的升级过程更轻松、更高效。 既然读到这里，你大概已经准备升级自己的 Docsy 项目——那就开始吧！ ## 升级项目 {#upgrading-your-project} 正如[上一篇文章](/zh/blog/2023/bootstrap-5-migration/#migrating-docsy-based-projects)所述，每个项目使用的 Bootstrap 与 Docsy 功能组合都不相同，因此 **你的升级之路很可能独一无二**。本节给出一些通用建议。 ### 升级 Docsy {#upgrade-docsy} 如果还没有这样做，请先把项目完整升级到 Docsy 0.6。每次 Docsy 发布都可能带来一组独立的升级挑战；实际规模与工作量取决于项目使用的功能，以及上一次升级距今有多久。先解决 0.7 之前的所有问题，才能专注于 Bootstrap 5。完成后，再升级到最新的 Docsy 0.7.x。 ### 处理 Bootstrap 变更 {#address-bootstrap-changes} 建议先通读 Bootstrap 5.2 的[迁移页面](https://getbootstrap.com/docs/5.2/migration/)，了解相较 Bootstrap 4 的变化范围。找出项目实际使用功能中的破坏性变更，再逐项解决。下面列举其中几类，最后还会说明如何处理其余问题。 有些 Bootstrap 变更会明显破坏站点布局或功能，例如 `ml-1`、`pr-2` 等[工具类重命名](https://getbootstrap.com/docs/5.2/migration/#utilities)。可以在项目自定义布局或文档页的内联 HTML 中使用正则表达式批量搜索替换。我曾使用以下表达式： - 外边距与内边距：`\b([mp])[lr](-([0-5]|auto))\b` - 左/右相关类：`\b((float|border|rounded|text)-)(left|right)\b` 如果项目使用下拉菜单、Popover 或 Tooltip 等 Bootstrap [JavaScript 插件](https://getbootstrap.com/docs/5.2/migration/#javascript)，那么在调整数据属性名称前，这些功能都会停止工作。新属性统一使用 `data-bs` 前缀进行命名空间隔离，例如应使用 `data-bs-toggle`，而不是 `data-toggle`。 还有一些 Bootstrap 破坏性变更需要更多工作，例如上一篇文章[摘要](/zh/blog/2023/bootstrap-5-migration/#tldr)中提到的： - [`media-breakpoint-down()` Mixin 参数需要上移](/zh/blog/2023/bootstrap-5-migration/#mixin-media-breakpoint-down-argument-shift) - [网格 `.row` 与 `.col` 样式变更具有破坏性](/zh/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking) - [Bootstrap Sass 文件导入顺序：必须先导入函数](/zh/blog/2023/bootstrap-5-migration/#import-ordering-of-bootstrap-sass-files-functions-first) Docsy 博客布局曾使用 `.media` 类，而它已被 [Bootstrap 5 删除](https://getbootstrap.com/docs/5.2/migration/#grid-updates)。这项变化与 [`.row`、`.col` 样式变更](/zh/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking)一起，导致博客布局经过数轮迭代，例如 [PR #1566](https://github.com/google/docsy/pull/1566)。如果项目覆盖了博客布局，就应仔细审阅这些更新；否则会自动获得相关变更，无需额外处理。 如果遇到本文没有提及、但会影响项目的 Bootstrap 5 破坏性变更，可以查看 Docsy [Issue #470：升级到 Bootstrap 5.2](https://github.com/google/docsy/issues/470)的首条说明。其中列出 50 个任务，分别处理不同的迁移问题，并附有说明或交叉引用的 PR，展示每个问题的解决方式。 ### 处理 Docsy 特有变更 {#address-docsy-specific-changes} 这里也应简要说明 Docsy 0.7 中与 Bootstrap 无关的主要变化： - `blocks/section` 的 `type` 参数默认值与可接受取值发生变化（[#1472](https://github.com/google/docsy/issues/1472)）； - 不再支持 Hugo 0.54.x 之前的 `{{% %}}` 行为（[#939](https://github.com/google/docsy/issues/939)）； - 要求 Hugo 0.110.0 或更高版本。 完整变更清单请查看 [0.7.0 CHANGELOG](/zh/project/about/changelog/#v0.7.0)。 ## 案例研究 {#case-studies} 下面通过 OpenTelemetry 项目与 Docsy 示例模板仓库，展示 Docsy 升级过程。 ### opentelemetry.io {#opentelemetryio} [多个 CNCF 项目](https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/)都使用 Docsy 主题，其中包括我用作 Docsy 预发布测试站的 [opentelemetry.io](https://opentelemetry.io/)。按照前述建议，我先把 Docsy 从 0.4 升级到 0.6（[opentelemetry.io Issue #2419](https://github.com/open-telemetry/opentelemetry.io/issues/2419)）。 升级到 Docsy 0.7 的过程[相当顺利](https://github.com/open-telemetry/opentelemetry.io/issues?q=label%3Adocsy+is%3Aclosed+closed%3A%3E2023-03-03)。除了工具类改名、数据属性命名空间等“显而易见”的变化，OTel 网站还需要完成以下项目专属调整： - [表单的破坏性变更](https://getbootstrap.com/docs/5.2/migration/#forms)要求大幅重做 [Registry](https://opentelemetry.io/ecosystem/registry/) 表单； - OTel 网站虽然没有覆盖博客布局，却在 Registry 条目中使用了已删除的 `.media` 类，因此改用 Flex 样式。 仅此而已。两项问题的具体解决方式见 OTel [PR #2490](https://github.com/open-telemetry/opentelemetry.io/pull/2490)。 ### Docsy-example {#docsy-example} [docsy-example](https://github.com/google/docsy-example) 是一个 [GitHub 模板](https://gitprotect.io/blog/how-to-use-github-repository-templates/)，我们通常建议准备[用 Docsy 创建新站点](/zh/docs/get-started/docsy-as-module/example-site-as-template/)的用户从这里起步。示例站支持[多语言](/zh/docs/language/)，这也影响了所需升级工作。 示例站升级甚至比 OTel 更简单。关键变更（[PR #221](https://github.com/google/docsy-example/pull/221)）主要集中在各语言的落地页： - 工具类从 `.ml-*`、`.mr-*` 等改为 `.ms-*`、`.me-*`； - [blocks/section](/zh/docs/content/shortcodes/#blocks-section) 发生变化（[PR #1472](https://github.com/google/docsy/pull/1472)）： - 语言落地页需要从 `.html` 改名为 `.md`，以便使用块短代码渲染 Markdown； - 对表示行的 `blocks/section` 元素改用 `type="row"`（也见 [PR #220](https://github.com/google/docsy-example/pull/220)）。 就这些。 ## 下一步是什么？ {#what-next} 如果项目没有覆盖任何 Docsy 布局，升级过程应该比较直接；反之，布局文件的每项变化都值得格外仔细地审查。 希望这些建议能让你的 Docsy 0.7 升级更顺畅。欢迎在 [0.7.0 讨论](https://github.com/google/docsy/discussions/1555)或[后续 0.7.x 版本](https://github.com/google/docsy/discussions/categories/announcement?discussions_q%3Dis%253Aopen%2Bcategory%253AAnnouncement)下留言，分享自己的经验。祝升级顺利！ 特别感谢 [Erin McKean](https://github.com/emckean) 对本文提出细致而宝贵的意见，也感谢所有参与 Docsy 0.7.x 系列版本的贡献者！