企业官网建设流程全解析

al-folio v1 如何为旧版 Bootstrap 标记内容启用兼容模式？

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio

如果你把基于旧版 al-folio 的内容升级到 v1.x，站点核心已经切换到 Tailwind-first，旧页面里的 Bootstrap 标记（row、col-*、card、btn，以及data-toggle的 collapse/dropdown/tooltip/popover 行为）默认不再由运行时接管。al-folio v1.x 为此提供了一个默认关闭的兼容模式，由al_folio_bootstrap_compatgem 提供：开启后构建会注入/assets/css/bootstrap-compat.css和/assets/js/bootstrap-compat.js，恢复旧版 Bootstrap 行为。本文给出在 v1.x 站点上启用该模式、验证构建产物、并在退出窗口结束前关闭它的完整路径。

适用前提与时间窗口

• 站点运行在 al-folio v1.x（al_folio.api_version: 1、al_folio.style_engine: tailwind的 starter 契约）。
• 内容确实依赖 Bootstrap 标记的类名或data-toggle行为；纯 Tailwind 标记不需要开启兼容模式。
• 兼容模式是有时限的：v1.2及之前支持，v1.3弃用（迁移警告会变得更严格），v2.0移除，届时它不再是官方运行时的一部分。这些时间点同时写在 starter 的 _config.yml 注释键support_window/deprecates_in/removed_in中，也与 docs/ARCHITECTURE.md 的“Bootstrap compatibility is opt-in and time-boxed”一节一致。

第一步：确认 gem 依赖已就位

兼容运行时由al_folio_bootstrap_compatgem 提供，starter 默认已把它接入依赖和插件清单，不需要手动添加，只需核对：

• Gemfile 的:al_folio_plugins分组中有gem 'al_folio_bootstrap_compat', '= 1.0.0'；
• _config.yml 的jekyll: plugins列表中有- al_folio_bootstrap_compat。

如果你是从更早版本自行迁移的站点（例如 docs/INSTALL.md “Older pre-v1 installs” 一节描述的重度定制仓库），需要保证这两处都包含该 gem，再运行bundle install使依赖生效。

第二步：在 _config.yml 中开启兼容开关

starter 中对应的默认配置如下（_config.yml）：

al_folio: compat: bootstrap: enabled: false support_window: v1.0-v1.2 deprecates_in: v1.3 removed_in: v2.0

把enabled改为true即可。docs/FAQ.md 与 docs/CUSTOMIZE.md 给出的最小配置同样是这三层compat: bootstrap: enabled: true结构，support_window等键是 starter 自带的说明性元数据，功能开关只有enabled。

第三步：重新构建并验证产物

修改配置后执行本地构建：

bundle exec jekyll build

判断是否生效的标准来自仓库自带的集成检查 test/integration_bootstrap_compat.sh，它对两种构建各做了明确的产物断言，你可以照同一标准核对_site：

默认构建（enabled: false）下，输出的index.html：

• 仍然包含/assets/css/tailwind.css；
• 不包含/assets/css/bootstrap-compat.css；
• 不包含任何 jQuery runtime 的<script src=...jquery...>引用。

开启兼容模式后，index.html必须同时包含对/assets/css/bootstrap-compat.css和/assets/js/bootstrap-compat.js的引用，并且输出目录下真实存在这两个文件：

grep -q '/assets/css/bootstrap-compat.css' _site/index.html grep -q '/assets/js/bootstrap-compat.js' _site/index.html ls _site/assets/css/bootstrap-compat.css _site/assets/js/bootstrap-compat.js

四条检查全部通过，说明兼容运行时已按预期注入。仓库集成脚本全绿时打印bootstrap compatibility integration checks passed，可作为整体验收信号。

注意这些资产不会提交在仓库里：al_folio_bootstrap_compat是在构建时按开关注入 JS/CSS 的 Generator，assets/下看不到它们是正常现象，只有开启后它们才会出现在_site/中（见 docs/ARCHITECTURE.md “How feature gems ship their assets”）。

可选分支：如果不想直接改动正式_config.yml，可以仿照集成脚本的做法，把覆盖配置写进一个临时 YAML 文件，再用多配置文件方式构建验证：

bundle exec jekyll build --config "_config.yml,compat-override.yml"

其中compat-override.yml的内容就是al_folio: compat: bootstrap: enabled: true三层结构。验证完毕后再把开关正式落到_config.yml。

开启后影响哪些行为

• 旧版data-toggle与 Bootstrap 类行为在 Tailwind-first 核心上恢复，覆盖row、col-*、card、btn等常见布局/内容模式和 collapse/dropdown/tooltip/popover（见 docs/CUSTOMIZE.md “Compatibility matrix”）。
• 表格行为会随之切换：enabled: true时pretty_table: true走 Bootstrap Table 运行时；enabled: false时 v1.x 用内置的 vanilla Tailwind 表格引擎处理table[data-toggle="table"]标记，同样支持搜索、分页、排序和点击选择。参考示例见 _posts/2023-03-21-tables.md。如果你的旧内容没有依赖 Bootstrap Table，可以评估是否根本不必开启兼容模式。

退出计划：迁移内容并关闭开关

兼容模式只解决过渡期，文档给出的收尾路径是逐步把内容迁出 Bootstrap 标记，并在v1.3前关闭该开关。可用 v1 的升级 CLI 审计和迁移：

# 审计站点中的破坏性/弃用模式 bundle exec al-folio upgrade audit # 应用确定性 codemods（可选） bundle exec al-folio upgrade apply --safe # 生成人工跟进报告 bundle exec al-folio upgrade report

报告写入al-folio-upgrade-report.md，发现项分为Blocking（目标升级完成前必须解决）和Non-blocking（可随时间逐步迁移的弃用模式），按此分类安排迁移即可（见 docs/INSTALL.md “Upgrading from a previous version”）。迁移完成后把al_folio.compat.bootstrap.enabled改回false，并按第三步的标准确认构建产物中不再出现bootstrap-compat.*资产。

边界说明

• 兼容模式只覆盖v1.2为止的时间窗，v2.0起不存在；不要在v2.0目标上继续依赖它。
• 它是 opt-in 的额外资产注入，不是默认行为：默认构建不应包含bootstrap-compat.css/js或 jQuery 引用，若默认构建里出现了这些资产，说明开关或本地文件被误加，应回到第一步核对配置。
• 更完整的兼容矩阵与升级流程见 docs/CUSTOMIZE.md “Bootstrap compatibility mode (v1.x)”和 docs/FAQ.md “How do I handle legacy Bootstrap-marked pages on Tailwind-first v1.x?”。

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio