把博客主题做成开源项目：Oneyer StuFlow 的设计与落地

写这个博客的第三个月，我终于把堆在本地迭代了十几版的静态原型整理成了正式的 WordPress 主题，并决定完整开源。它叫 Oneyer StuFlow，一个面向技术博客的经典两栏主题：毛玻璃导航、渐变卡片流、悬浮目录、时间线归档，全部功能只依赖 WordPress 核心，不依赖任何付费插件——连代码高亮都可以交给任何你喜欢的插件，主题只负责把结构留对。

这篇文章记录从原型到主题过程中的关键决策、环境要求和几个印象深刻的坑。项目地址在 GitHub · yexli/StuFlow，欢迎 Issue 和 PR。

这个主题想解决什么问题

市面上的中文博客主题大多往两个极端走：要么重到把首页做成门户，要么轻到只剩一列文字。我想要的是中间那条线——首页像杂志，正文像书页。列表页负责「逛」，详情页负责「读」，两套视觉节奏互不干扰。

具体拆成三条硬性要求：

• 首页卡片流必须有呼吸感，渐变封面直接从分类语义生成，不强迫每篇文章都配图；
• 长文必须有悬浮目录和滚动定位，跳转不抖动；
• 正文排版交给一套统一的 .prose 契约，不管内容是经典编辑器还是 Gutenberg 写的，渲染结果一致。

设计上的三个关键决策

毛玻璃导航 + 渐变卡片流

导航栏用 backdrop-filter: blur() 做毛玻璃，滚动时吸顶。卡片封面不用真图，而是按主分类映射一组渐变色，配合噪点纹理，让「没配图的文章」也有稳定的视觉重量。首批渐变只做了六组，原本想覆盖全部分类，后来发现克制的色板反而更耐看。

悬浮目录：只认 h2 和 h3

目录通过一个 the_content 过滤器在渲染时扫描 h2 / h3 并注入锚点 id，收集结果暂存在全局变量里，供侧栏渲染。正文章节不足时目录自动隐藏，侧栏让位给「本文数据」（阅读时长、字数、评论数）。

内容结构层过滤器链

主题在 the_content 上挂了四个优先级串联的过滤器：标题锚点 → 代码块包裹 → 表格包裹 → 提示框解析。比如一段普通的 <pre>，会被自动包上 macOS 风格的窗口栏、语言徽标和复制按钮；首行写 # file: xxx 还会提取出文件名：

# file: setup-env.sh
# 一键校验主题运行环境
wp core version
php -v | head -n 1
mysql --version
echo "theme check done"

提示框则复用了经典编辑器的引用语法，写起来零成本：

环境要求与兼容性

主题刻意把依赖压到最低，官方支持矩阵如下：

界面速览

踩坑记录

三个印象最深的坑，都和「自以为正确」有关：

• wpautop 会先跑。过滤器链的优先级必须排在 10/11 之后，否则拿到的 HTML 还是未分段的原始文本；
• 旁路渲染污染目录。相关文章的摘要也会走 the_content，不拦截的话悬浮目录会被别的文章的标题覆盖，只能精确判定「正在渲染主查询本身」才放行；
• 搜索框快捷键。全局 Ctrl + K 唤起搜索看似简单，处理输入法组合键（IME composition）花掉的时间是其余逻辑的总和。

路线图

1. 暗色模式跟随系统，手动开关做进导航栏；
2. 归档页时间线的年份锚点与键盘导航；
3. 把后台设置页的选项抽成可导出的预设（正在写文档）；
4. 评论支持 Webmention。（排在最后，因为它最不重要）

开源对我来说是把双刃剑：代码要经得起陌生人审视，节奏也被 Issue 推着走。但让一个主题在别人的站点上继续生长，比自己藏着迭代有趣得多。如果你也在折腾 WordPress 博客，欢迎拿去改，改好了告诉我一声就好。