如何将 Jekyll 博客主题移植到 Python：来自实际操作的教训
内容提要
作者将 Tufte 风格的 Jekyll 博客主题移植为 Python 版 tufte-python，以使用熟悉工具链并深入理解静态站点生成器。文章分七步：盘点原主题组件、合并配置、用文本预处理实现自定义标签、以可换主题的纯 CSS 替代 Sass、自建增量构建缓存、用 GitHub Actions 部署，并强调需用真实旧文章验证功能一致性，而非仅看构建成功。
延伸解读
移植主题的常见陷阱：本地预览与生产环境不一致
文章指出，本地 `--serve` 预览会故意忽略 `baseurl`，导致链接和资源从根路径解析，而部署到子目录时却需要正确的 `baseurl`。这种差异是静态站点在子目录下“本地正常、线上 404”的典型原因。作者建议在部署前用 `--production-urls` 模式测试，以提前发现路径问题。
自定义标签移植：为何不能直接套用 Jinja2 语法
Jekyll 的 Liquid 自定义标签在 Markdown 渲染前被替换为 HTML，而 Jinja2 的标签系统面向模板逻辑，不适合解析 Markdown 中的任意引号参数。若强行移植，所有旧文章都需重写，违背“即插即用”的初衷。作者最终采用文本预处理，用正则和 shlex 解析标签，再交给 Markdown 渲染，从而保持原有语法不变。
增量构建缓存：只跟踪文章修改时间不够
作者最初仅根据每篇文章的修改时间决定是否重新渲染，结果修改共享模板后，只有当天碰过的文章更新，其余文章仍保留旧 HTML。修复方法是额外跟踪全局构建输入（模板、配置、生成器源码）的最新修改时间，一旦这些文件更新，就强制全量重建。这牺牲一次较慢的构建，但避免了静默发布过时页面。
验证移植正确性：真实旧文章比构建成功更重要
文章强调，构建成功不等于移植正确。作者在测试中故意使用原主题的真实旧文章，而非专门编写的简单示例，从而发现了引号解析错误和代码块内标签被误展开的问题。此外，还需测试引号边界情况、响应式行为等。这些实践表明，只有用真实内容验证，才能确保功能一致性。
Q&A
为什么作者要把 Jekyll 主题移植到 Python？
作者想要一个自己熟悉的工具链，避免为了维护博客而处理不熟悉的 Ruby 环境；同时通过移植深入理解静态站点生成器的工作原理。
移植 Jekyll 主题到 Python 需要哪些前置知识？
需要基础 Python（虚拟环境、阅读他人代码）、Git 和 GitHub 账号、熟悉 Markdown 和 Git，以及基本了解 Jekyll 项目结构（_config.yml、_layouts/、_includes/ 和 Liquid 模板语法）。不需要 Jinja2 经验。
如何将 Jekyll 的自定义 Liquid 标签转换为 Python 实现？
将标签语法视为纯文本，在 Markdown 渲染前用正则表达式扫描并替换为 HTML。使用 shlex 解析带引号的参数，通过 HANDLERS 字典分发到对应的处理函数，并注意处理代码块中的标签以避免误替换。
移植过程中常见的坑有哪些？
常见坑包括：参数分割未处理引号导致参数错位；正则表达式误匹配代码块中的标签；增量构建缓存未考虑模板变更导致页面未更新；以及 GitHub Pages 部署时未正确设置 baseurl 或未将源设置为 GitHub Actions。
如何为 Python 静态站点生成器实现增量构建缓存？
使用 JSON 文件记录每个文档的修改时间，并额外跟踪全局输入（模板、配置文件、生成器源码）的最新修改时间。如果全局输入有更新，则强制全量重建，否则仅重建修改过的文档。
如何用 GitHub Actions 部署 Python 静态站点？
在 .github/workflows/deploy.yml 中定义工作流：检出代码、安装 Python 和依赖、运行 build.py 生成 _site 目录，然后上传为 Pages 工件并部署。需在仓库设置中将 Pages 源设为 GitHub Actions。
移植后如何验证功能一致性？
使用原主题的真实旧文章进行测试，而非仅用演示内容；故意测试引号边缘情况（如撇号、转义引号）；检查响应式行为，确保窄屏下 sidenote 和 margin note 正常。
