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.xal_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.ymlal_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 的 Generatorassets/下看不到它们是正常现象只有开启后它们才会出现在_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-toggletable]标记同样支持搜索、分页、排序和点击选择。参考示例见 _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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考