只用 Python 标准库,写一个静态博客生成器
这个博客没有用 Hugo、Astro,而是用一个六百来行、只依赖 Python 标准库的脚本生成。记录一下 Markdown 解析、构建期代码高亮、把另一个项目的内容嵌进来、站内搜索和原子发布这几块是怎么做的。
这个博客没有用 Hugo、Hexo 或 Astro,而是自己写了一个生成器 build.py:六百来行,只用 Python 标准库,python build.py 一条命令把 content/ 里的 Markdown 变成 dist/ 里的静态页面。
选择自己写,原因很简单:
- 零依赖:任何装了 Python 的机器都能构建,不用
npm install,也不怕哪天某个主题停更。 - 样式完全自己掌控:用现成主题时,想改一个细节往往要覆盖一层又一层的模板。
- 够用就好:个人博客要的功能其实不多——文章、标签、归档、搜索、RSS。
目录结构
homepage/
├── content/
│ ├── posts/2026-11-18-xxx.md # 文章:文件名里的英文部分就是网址
│ └── about.md
├── site.json # 站名、导航、专栏、备案号、开源推荐的来源
├── src/style.css src/main.js # 样式和前端交互
├── build.py # 生成器
└── deploy.sh # 生成 + 发布文章开头用 --- 包一段元信息,生成器按行切成键值对,不引入 YAML 解析库:
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.是列表,|是表格,三个反引号开始代码块,其余连续的行合成一个段落。 - 行内:对每段文字依次做替换。
行内替换的顺序很关键:先做 HTML 转义,再处理行内代码,然后是图片、链接,最后才是加粗和斜体。图片要排在链接前面,否则  会先被当成链接吃掉一半。
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,页面不用再加载任何高亮脚本。
做法是把几类规则拼成一个带命名分组的大正则,从左到右扫一遍,谁先匹配上就归谁:
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,没装就原样复制,不影响构建。
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 或 / 打开搜索框时才去加载它,之后全部在浏览器里匹配,不需要任何后端。文章量在几百篇以内,这种做法又快又省事。
样式和脚本的缓存
样式和脚本的地址后面带上文件内容的哈希:
data = (ROOT / 'src' / name).read_bytes()
VER[name] = hashlib.sha1(data).hexdigest()[:8] # → /assets/style.css?v=3f2a9c1e服务器上 /assets/ 一律缓存 30 天;内容一改,哈希就变,浏览器会自动拿新版本。
原子发布
发布脚本不直接覆盖网站目录,而是每次解压到一个新的版本目录,再把 current 软链接一次性切过去:
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/currentmv -T 用的是 rename 系统调用,切换是原子的:访问者不会看到传了一半的页面。出问题时把软链接指回上一个版本,就完成了回滚。
一个 Windows 上的小坑
本地预览时我在 dist/ 里起了 python -m http.server,结果再构建时 shutil.rmtree(dist) 报了 PermissionError:Windows 不允许删除某个进程的当前工作目录。改成只清空目录里的内容、保留目录本身就好了:
DIST.mkdir(exist_ok=True)
for child in DIST.iterdir():
shutil.rmtree(child) if child.is_dir() else child.unlink()小结
自己写生成器的成本并不高,换来的是对每个细节的完全掌控。代价是很多现成主题自带的功能要自己补,比如评论、分页和多语言——不过对一个个人技术博客来说,这些正好都可以先不要。