工程实践

只用 Python 标准库,写一个静态博客生成器

这个博客没有用 Hugo、Astro,而是用一个六百来行、只依赖 Python 标准库的脚本生成。记录一下 Markdown 解析、构建期代码高亮、把另一个项目的内容嵌进来、站内搜索和原子发布这几块是怎么做的。

这个博客没有用 Hugo、Hexo 或 Astro,而是自己写了一个生成器 build.py:六百来行,只用 Python 标准库,python build.py 一条命令把 content/ 里的 Markdown 变成 dist/ 里的静态页面。

选择自己写,原因很简单:

  • 零依赖:任何装了 Python 的机器都能构建,不用 npm install,也不怕哪天某个主题停更。
  • 样式完全自己掌控:用现成主题时,想改一个细节往往要覆盖一层又一层的模板。
  • 够用就好:个人博客要的功能其实不多——文章、标签、归档、搜索、RSS。

目录结构

Text
homepage/
├── content/
│   ├── posts/2026-11-18-xxx.md   # 文章:文件名里的英文部分就是网址
│   └── about.md
├── site.json                     # 站名、导航、专栏、备案号、开源推荐的来源
├── src/style.css  src/main.js    # 样式和前端交互
├── build.py                      # 生成器
└── deploy.sh                     # 生成 + 发布

文章开头用 --- 包一段元信息,生成器按行切成键值对,不引入 YAML 解析库:

Python
def parse(path):
    raw = path.read_text(encoding='utf-8')
    m = re.match(r'^---\n(.*?)\n---\n(.*)$', raw, re.S)
    meta, body = {}, raw
    if m:
        body = m[2]
        for line in m[1].splitlines():
            if ':' in line:
                k, v = line.split(':', 1)
                meta[k.strip()] = v.strip()
    return meta, body

一个够用的 Markdown 解析器

完整的 CommonMark 规范很复杂,但博客里常用的只有标题、段落、列表、引用、表格、代码块、图片和链接。解析分两层:

  1. 块级:逐行扫描,看行首决定进入哪种块——# 是标题,> 是引用,- 或 1. 是列表,| 是表格,三个反引号开始代码块,其余连续的行合成一个段落。
  2. 行内:对每段文字依次做替换。

行内替换的顺序很关键:先做 HTML 转义,再处理行内代码,然后是图片、链接,最后才是加粗和斜体。图片要排在链接前面,否则 ![图](a.png) 会先被当成链接吃掉一半。

Python
def inline(s):
    s = html.escape(s, quote=False)
    s = re.sub(r'`([^`]+)`', r'<code>\1</code>', s)
    s = re.sub(r'!\[([^\]]*)\]\(([^)\s]+)\)', r'<img src="\2" alt="\1">', s)
    s = re.sub(r'\[([^\]]+)\]\(([^)\s]+)\)', r'<a href="\2">\1</a>', s)
    s = re.sub(r'\*\*([^*]+)\*\*', r'<strong>\1</strong>', s)
    return s

构建期代码高亮

代码高亮没有引入 Prism 或 highlight.js,而是在生成时用一组正则把代码切成注释、字符串、关键字、数字几类,包上不同的 class。浏览器拿到的已经是上好色的 HTML,页面不用再加载任何高亮脚本。

做法是把几类规则拼成一个带命名分组的大正则,从左到右扫一遍,谁先匹配上就归谁:

Python
parts = [f'(?P<c>{COMMENT[lang]})',                         # 注释,按语言区分
         r'(?P<s>"(?:\\.|[^"\\\n])*"|\'(?:\\.|[^\'\\\n])*\')',  # 字符串
         r'(?P<n>\b\d+(?:\.\d+)?\b)',                          # 数字
         r'(?P<w>[A-Za-z_$][\w$-]*)']                          # 单词
TOKEN = re.compile('|'.join(parts), re.M)

这样能保证字符串里的 // 不会被误判成注释。注释的写法按语言区分:JavaScript 是 // 和 /* */,Shell、Python、nginx 是 #。匹配到的单词再查一遍这门语言的关键字表,后面紧跟 ( 的当成函数名。代码块顶部标出语言,右上角还有一个「复制」按钮,点一下把原始代码放进剪贴板。

把另一个项目的内容嵌进来

「开源推荐」栏目的内容在另一个仓库里维护:每期一个目录,里面有 README.md(正文)、meta.json(结构化信息)和截图,外加一个总的 picks/index.json。生成器不复制、不改动那边的文件,只在构建时读取:

  • site.json 里用一个相对路径 oss_source 指过去,那边新增一期,这边重新构建就会出现;
  • 页面头部的期号、名称、协议、Star 数、版本直接取 meta.json 的字段,不去解析正文;
  • 正文按二级标题切段,「框架名」一段的表格变成参数卡片,「作品展示」一段换成卡片墙:截图、类型、说明,能嵌入的作品可以页内预览,点了才加载对方的页面;
  • 截图在构建时转成 WebP,各出一张 1280 宽的大图和 640 宽的缩略图,用 srcset 让手机只下载小图。这一步用到 Pillow,没装就原样复制,不影响构建。
Python
def save_image(src, dst_stem, widths=(1280, 640)):
    im = Image.open(src).convert('RGB')
    for w in widths:
        out = dst_stem.parent / f'{dst_stem.name}-{w}.webp'
        small = im.resize((w, round(im.height * w / im.width)), Image.LANCZOS) if im.width > w else im
        small.save(out, 'WEBP', quality=80, method=6)

前两期的截图原本约 1.8 MB,转完大图加缩略图一共 1.2 MB 左右,而手机上实际只加载缩略图。

站内搜索

生成时顺手输出一份 search.json,包含每篇文章和每期开源推荐的标题、摘要、标签和正文纯文本。按 Ctrl + K 或 / 打开搜索框时才去加载它,之后全部在浏览器里匹配,不需要任何后端。文章量在几百篇以内,这种做法又快又省事。

样式和脚本的缓存

样式和脚本的地址后面带上文件内容的哈希:

Python
data = (ROOT / 'src' / name).read_bytes()
VER[name] = hashlib.sha1(data).hexdigest()[:8]   # → /assets/style.css?v=3f2a9c1e

服务器上 /assets/ 一律缓存 30 天;内容一改,哈希就变,浏览器会自动拿新版本。

原子发布

发布脚本不直接覆盖网站目录,而是每次解压到一个新的版本目录,再把 current 软链接一次性切过去:

Bash
REL=/var/www/site/releases/$(date +%Y%m%d-%H%M%S)
mkdir -p "$REL" && tar -xzf /tmp/site.tgz -C "$REL"
ln -sfn "$REL" /var/www/site/current.new
mv -Tf /var/www/site/current.new /var/www/site/current

mv -T 用的是 rename 系统调用,切换是原子的:访问者不会看到传了一半的页面。出问题时把软链接指回上一个版本,就完成了回滚。

一个 Windows 上的小坑

本地预览时我在 dist/ 里起了 python -m http.server,结果再构建时 shutil.rmtree(dist) 报了 PermissionError:Windows 不允许删除某个进程的当前工作目录。改成只清空目录里的内容、保留目录本身就好了:

Python
DIST.mkdir(exist_ok=True)
for child in DIST.iterdir():
    shutil.rmtree(child) if child.is_dir() else child.unlink()

小结

自己写生成器的成本并不高,换来的是对每个细节的完全掌控。代价是很多现成主题自带的功能要自己补,比如评论、分页和多语言——不过对一个个人技术博客来说,这些正好都可以先不要。