如何将Jekyll博客主题移植到Python环境中：实际操作中的经验与教训
几年来，我一直在使用一个采用 tufte-jekyll 样式设计的博客，正是这个经历让我发现了Edward Tufte所提出的布局理念。 Edward Tufte 因在数据可视化与信息设计领域的贡献而闻名，他是高数据密度设计的坚定支持者，同时也极力反对使用那些毫无意义的视觉元素。 tufte-css （以及它的许多衍生版本）为网页设计带来了诸多优势：充足的空白空间、适合阅读的排版格式，还有用于提供补充信息的 侧边注释 （而非干扰用户体验的弹出窗口）。 除了那些与写作无关的部分外，我对 tufe-jekyll 博客的设计几乎毫无意见。这个基于 Jekyll 框架、使用 Ruby 语言开发的版本，
几年来，我一直在使用一个采用tufte-jekyll样式设计的博客，正是这个经历让我发现了Edward Tufte所提出的布局理念。
Edward Tufte因在数据可视化与信息设计领域的贡献而闻名，他是高数据密度设计的坚定支持者，同时也极力反对使用那些毫无意义的视觉元素。
tufte-css（以及它的许多衍生版本）为网页设计带来了诸多优势：充足的空白空间、适合阅读的排版格式，还有用于提供补充信息的侧边注释（而非干扰用户体验的弹出窗口）。
除了那些与写作无关的部分外，我对tufe-jekyll博客的设计几乎毫无意见。这个基于Jekyll框架、使用Ruby语言开发的版本，我只是为了这个项目才使用了它。
因此，我决定用Python重新编写整个主题代码。并不是因为Jekyll不好，而是因为我想使用自己熟悉的技术工具链。同时，我也想验证自己是否真正理解了静态网站生成器的工作原理。
tufte-python就是这样一个衍生版本，而这篇文章则起到了指导作用——它详细说明了当您将基于Ruby的Jekyll主题迁移到Python环境时，实际需要做哪些调整，以及我在最初尝试过程中犯过的具体错误。
这些内容并不专门针对Jekyll而言。无论您的目标平台是Hugo（Go语言）、Eleventy（JavaScript）还是其他技术栈，这些原则都是适用的。
通过学习这些内容，您不仅能掌握具体的技术细节，还能学会如何系统地分析问题。如果您正在迁移不同的主题代码，或者将一个主题适配到完全不同的编程语言环境中，请记住：虽然语法会发生变化，但面对的挑战本质上是相同的。
目录
但是等等，为什么要用静态博客呢？
与动态网站相比，静态网站的发布流程要简单得多。具体来说，这个流程包括五个步骤：
编写一个Markdown文件。
运行生成工具。
预览并检查生成的结果。
将源代码提交到版本控制系统中。
让GitHub Actions来发布网站内容。
对于我来说，这样的流程已经足够满足我的需求了——我只是偶尔会在个人开发博客上发布一些文章。这种流程使得内容可以在文本编辑器中轻松查看，而且任何修改都便于检查。
与它的前身一样，实际的代码库仍然使用了Jinja2模板、Markdown格式以及YAML格式来组织内容结构。通过GitHub Actions的自动化流程，这些生成的文件会被部署到GitHub Pages上。
为什么要自行修改主题而不是直接使用原版呢？
采取这种做法有很多原因。
首先，也许你不想使用那些在其他地方根本用不到的工具。对我来说，我的机器上安装了Ruby，仅仅就是为了使用它的这个功能。然而，这个工具实在太不稳定了，以至于“更新博客”这个简单的操作，往往首先会变成“修复我的Ruby开发环境”这样的复杂任务。
或者，也许你每天都在使用目标语言进行开发，因此你更愿意阅读并修改那些自己熟悉的工具和代码，而不是去学习另一个开发生态系统的知识，仅仅为了最终能够调整某个插件文件。
又或者，你可能希望真正了解静态网站生成器的原理，而不仅仅是会使用它们。通过自行修改主题，你会被迫仔细研究每一个模板、每一个自定义标签以及每一个构建步骤，从而深入理解其工作原理。这种学习方式与只是“知道它能用”是完全不同的，它是掌握这项技能的最佳途径之一。
你需要准备什么
具备基本的Python知识：了解虚拟环境以及如何阅读他人的代码。
需要安装Git并拥有GitHub账户，因为最终发布的内容都会托管在GitHub Pages上。
需要了解Jekyll网站构建工具的一些基本概念，包括：
_config.yml文件、_layouts/目录、_includes/文件夹以及Liquid模板的语法。不需要事先具备Jinja2的使用经验。实际上，Jinja2在概念上与Liquid非常相似，因此在学习过程中你会自然而然地掌握它。
先查看最终成果：让端口正常运行起来
在介绍这个项目究竟是如何构建起来的之前（包括其中出现问题的部分），先了解一下它的最终形态会是什么样子是很有必要的。我所说的这个主题已经作为一个可以立即使用的项目存在了。tufte-python附带了自己的使用教程，你可以在几分钟内就在本地环境中让它正常运行。
在阅读接下来的内容时，这个项目可以为你提供一个具体的参考对象；如果你想直接使用现有的版本而不是从零开始重新开发，它也是一个很好的选择。
准备工作
首先，克隆这个项目，并将其指向你自己的代码仓库（或者直接创建一个分支）。
首先在GitHub上创建一个新的空代码仓库，给它起个名字，比如my-blog：
git clone https://github.com/hyperphantasia/tufte-python.git my-blog
cd my-blog
接下来，将远程仓库的地址设置为你的代码仓库地址：
git remote set-url origin
然后推送项目到远程仓库：
git push -u origin main
接下来，在虚拟环境中安装项目所需的依赖库：
python -m venv .venv
# 根据你的操作系统进行相应的操作
# source .venv/bin/activate # macOS/Linux系统
# .venv\Scripts\Activate.ps1 # Windows PowerShell系统
pip install -r requirements.txt
在第一次构建项目之前，你需要设置一些基本的配置参数。
打开项目根目录下的config.yml文件：
title: "网络中的一个宁静角落"
author: "你的名字"
email: "you@example.com"
url: "https://yourusername.github.io"
baseurl: "/my-blog" # 如果这是个人或组织的页面，可以使用""作为基地址
permalink: "/articles/{year}/{slug}/"
theme: "solAArized"
options:
mathjax: true
如果你打算将项目发布在https://yourusername.github.io/my-blog/这个地址上，那么baseurl必须与代码仓库的名称完全匹配，即前面要有斜杠，后面不能有斜杠。如果这个设置不正确，部署后的网站上的所有内部链接和样式表引用都会出现404错误，而在本地环境中这些链接却是可以正常使用的（具体原因会在下文中说明）。
最后，构建项目并预览效果：
python build.py --serve --watch
通常情况下，打开终端中显示的地址http://localhost:8000，你应该就能看到已经存在于content/目录中的演示内容。保持--watch选项处于开启状态，然后尝试编辑一篇文章：系统会自动重新构建页面，而你不需要再次运行任何命令。
有件事现在就了解一下，否则以后可能会让你浪费一整个下午的时间去解决困惑：当地的 `--serve` 预览功能会故意忽略 `baseurl` 参数，因此链接和资源文件会从你的 开发服务器 的根目录开始被加载，而不是从某个子目录中加载。
如果你想查看网站在部署后的实际效果，包括真正的 baseurl，那么应该运行 `python build.py --serve --production-urls` 命令。这个命令会使用生产环境的 URL 结构来预览网站。
正是这种区别导致了那些位于子目录中的静态网站在本地可以正常显示，但在生产环境中却会出现问题。因此，在真正部署之前，至少应该仔细测试这两种模式各一次。
撰写你的第一篇文章
你可以将自己的内容用来测试这个主题的功能，而不仅仅是使用演示用的示例内容。创建一个文件 `content/posts/2024-06-07-hello.md`，然后尝试编写内容：
---
title: "Hello, Margins"
date: 2024-06-07 14:30:00
categories: notes
tags: [smile, writing]
---
{% newthought '一个新的想法' %} 可以用来创建一个新的段落，而无需使用标题标签。
这里有一个旁注 {% sidenote 'note-1' '在宽屏设备上，这个旁注会显示在页面的右侧边栏；而在窄屏设备上，则会显示在一个可点击的链接后面。%' %}，让你可以尝试一下这个让我最初想要使用这个主题的功能。
<> 
2026 Copyright © 上海知力信息科技有限公司 · All Rights Reserved
沪ICP备09012674号 
沪公网安备 31011502018658号 增值电信业务许可证：沪B2-20220251