Kratos Yang —— 一个给中文技术博客用的 WordPress 主题

上游是 Kratos，在老杨手里改了两百多轮，改成一个偏「写作与阅读」的形状：写的时候少折腾，读的时候少干扰，后台能看见的东西尽量不靠插件。

当前版本 4.2.1。下面按「你会用到的顺序」讲，每块都写了怎么开和为什么要这么设计 —— 后者比前者重要，因为很多设置的意义只有踩过一次才知道。

一、装好之后先做这三件事

1. 设一次主色。后台「主题设置 → 全站配置」。主色会带动输入框边框、链接、按钮、目录高亮、回复那条竖线 —— 全套一起变，不用逐处调。
2. 选一张 404 配图。同一个页面里。默认那张是主题自带的，换成自己的图之后，走错地址的访客至少能看到点人味。
3. 看一遍「主题设置」的左侧标签栏。左边一共十几个分组，右侧只显示当前那组。想找某项设置先看左边，别在单页里往下滚 —— 早前版本是长单页，滚到底部找「自动头像」是件很痛苦的事情。

二、正文排版：标题、目录、代码、图片

标题自动编号
文章正文里的 h1 到 h4 会按层级自动加 1 / 1.1 / 1.1.1 这样的编号，和右侧目录的数字对齐。写作时不用自己敲序号 —— 敲了就重复了（主题不会去重，它只管按结构生成）。
没有 h1 的文章，h2 就当一级，编号从 1 开始，不会出现「2 下面直接跟 3」这种断档。

自动目录（TOC）
长文必备，两种用法，可以同时开：
· 手动：在正文任意位置写一行 [TOC]，那里就长出目录。可带参数 [TOC title="本文目录" levels="1,2,3" numbering="1" toggle="0" open="0"]。手写参数优先于后台设置，没写的才回落后台。
· 自动：后台「文章配置 → 自动目录」里开，正文一个字都不用写。

自动模式有两个独立开关，不是二选一：
· 在正文中显示 —— 还能选对齐（靠左 / 靠右）和插入位置（文章开头 / 第一个标题之前 / 文章结尾）。
· 浮动显示 —— 选浮在页边左侧还是右侧。
两个都开时，同一篇文章里会有一份正文内目录 + 一份浮动目录，指向同一批锚点，点哪份都跳同一处。默认状态（展开 / 收起）也能分开设。

每一个 levels 选项都认 "1,2,3" 这种写法。只收 h2/h3 就写 "2,3"。

代码高亮
不依赖任何高亮插件，主题自带一套（highlight.js 自托管）。Ender / Prism / Enlighter 那类插件可以卸掉，装多了反而打架 —— 早期版本同时开两个，会出现复制按钮变两个、行号叠成重影。

· 20 套配色：10 浅 + 10 深（GitHub、VS、Atom One、IntelliJ、Monokai、Night Owl、Dracula 系、Srcery、Panda……）。后台「文章配置 → 代码高亮」里选，选完当场在后台就能看到效果。
· 只加载选中的那一套。20 套全加载约 50KB（gzip 后约 15KB），没必要。所以换配色只是换一个 CSS 文件，不会拖慢页面。
· 语言标签：代码块左上角标出语言。代码围栏没写语言时会去猜，猜不准就标「可能」。
· 复制按钮：复制的是纯代码，不含行号 —— 带行号粘出去是没法直接跑的。
· 深色配色配深色卡片：选深色主题时，代码卡片底色也跟着变深。这条要单独做，否则深色代码贴在白卡片上，看着像没加载完。

图片灯箱
正文图片点一下在当前页放大，不跳走。多张图可以左右切换，键盘方向键也能翻。
后台「文章配置 → 图片灯箱」里可关。关了之后图片恢复成普通链接行为。

引用块
引用块内的文字和正文左边缘对齐，靠首尾引号区分层级，不靠缩进 —— 缩进会把引用块整体往右推 22px，读起来像掉进一个坑。

三、评论区

评论框是所见即所得：加粗、斜体、链接、引用、代码，点工具条就出效果，不用记 Markdown 语法。工具条在输入框上方。

· 回复层级按颜色区分，不靠缩进堆叠。缩进三层之后正文会被挤成一条窄缝。
· 评论区也能贴代码，和正文用同一套高亮。语言下拉里只列真正支持的，不会让你选了得到一个白板。
· 评论关闭时，整块彻底消失，不留一个空框加一句「评论已关闭」。
· 和评论插件共存：如果装了第三方评论系统，主题这块会让位，不会两边各画一个框。

四、头像：没上传头像的人不该是灰色神秘人

WordPress 默认对没设头像的访客显示一个灰底神秘人，一整屏评论全是同一个灰脸，很难分清谁是谁。

主题的做法是：按邮箱地址由主题在服务器端生成一张头像，直接以 data URI 内嵌到 img 标签里。同一个邮箱永远得到同一张脸，换台设备、换个浏览器也一样。图片是 SVG，由主题自己的模板拼出来，不请求任何外部服务、也不落盘存文件 —— 访客的邮箱不会因为看评论就发给别人。

怎么开：后台「自动头像」这一组里勾选「启用自动头像」，再选风格（共 18 套，点风格名能看到实时预览）。「注册用户保留原头像」默认开着 —— 只给查不到本站账号的邮箱生成图，作者自己上传的头像不会被盖掉。选完保存即可，不用清缓存 —— 头像是每次请求现算的。

· 18 套风格，全部可商用、不要求署名：lorelei、notionists、open-peeps、shapes、glass、rings、identicon、thumbs、pixel-art、icons、initials、avataaars、bottts 等，部分带 -neutral 变体。
· 人脸类风格只保留黄种人肤色区间。上游把全色谱都放出来了，本站是中文站，不合适的色号直接去掉。
· 本站注册用户保留他自己的头像，只有查不到邮箱的访客才生成 —— 别把用户自己传的图顶掉。

五、侧栏挂件

主题自带七个，都是自己写的，不依赖插件，样式统一：

· 个人简介 —— 头像、昵称、一句话简介、背景图。背景图会自适应挂件宽度，不会撑爆。
· 最近评论 —— 替代 Comments Widget Plus 那类插件。
· 文章分类 —— 替代 WP 自带的分类挂件，样式跟其他挂件一致（自带那个是裸 <ul>，插在中间很突兀）。
· 文章聚合 —— 按热度 / 最新 / 随机取文章，可设显示条数和时间窗。
· 搜索、标签云、广告位。

挂件标题都能自己改。标签云的列数可配。

⚠️ 一个坑：WP 5.8 之后后台「小工具」页默认被换成区块编辑器，老式挂件拖不进去。主题已做兼容，但如果你的 WP 版本较新、又装了几个也改这块的插件，可能被抢回去 —— 表现是「找不到可拖动的挂件」。这时候先把冲突插件停掉再看。

六、归档短代码 [Archives]

一篇文章里列出全站所有文章，按年 / 月归类，右上角四角有年份切换。

[Archives] —— 注意首字母大写。WordPress 的短代码标签区分大小写，写成 [archives] 不生效（这条踩过，注释里当初还写反了）。

每行显示浏览数、评论数、点赞数。评论关闭时这一整块不显示，不会留一个空壳。

其他短代码：[TOC] 目录、[bdbtn] 按钮、[kbd] 键盘键、[mark] 高亮、[accordion] 折叠、各种提示框（[info] / [success] / [warning] / [danger] 及带 box 后缀的块级版本）、[bilibili] / [youtube] / [vqq] / [music] 媒体嵌入。

七、导航

支持多级下拉（三级以内看着最舒服）。移动端是汉堡菜单，点开有过渡动画。

顶部那一条可以选：图片 Logo / 文字标题、背景色或背景图、主标题与副标题文案。Chrome 移动端地址栏的颜色也能单独设（不影响其他浏览器）。

八、CDN 加速

一个地址 + 一份白名单 + 一份黑名单，就这三样。

· 白名单：哪些路径走 CDN。
· 黑名单：哪些绝对不走，优先级高于白名单。
· 后台「主题设置 → CDN 加速」里有启用开关，白名单黑名单都预填好了，装好就能用，也能随手改。

⚠️ 两个容易翻车的点：
· 黑名单里一定要有后台路径（/wp-admin/）。CDN 缓存了后台页面，会出现「改了设置不生效」这种最难查的问题。
· 换 CDN 域名之后，记得清一次 CDN 那边的缓存。主题这边改配置不会自动通知 CDN。

九、邮件通知

评论被回复时给被回复的人发一封邮件。走 SMTP，不依赖服务器的 mail()（那个基本都会进垃圾箱）。

· 后台「主题设置 → 邮件通知」填 SMTP 主机、端口、账号、密码、加密方式。
· 有「测试邮件」按钮。发测试之前先保存 —— 早期版本这里有个 bug，点测试会把没保存的字段一并清空。
· 邮件版式是主题自己渲染的（白底 + 深色头部 + 暖色点缀），不是 WordPress 默认那封纯文本。

十、写作增强：四个引擎

发布文章时自动生成四样东西，各自独立开关：

· 别名（slug） —— 中文标题转成英文短链接。这辈子只有这一个引擎需要外部服务（翻译），其余三个纯本地。
· 标签 —— 两路取词：一路对着站里已有的几百个标签做最大匹配（那份标签库本身就是最好的领域词典），另一路从正文里找词典没覆盖的新词。排序看这篇文章自己的显著度：标题里出现的词权重最高，全站用得越泛的词罚得越重。
· 分类 —— 按内容判断归到已有分类。
· 摘要 —— 取正文前几句，按句子边界切，不按字数硬切（硬切会把一句话砍成两半）。

翻译服务可选百度翻译或有道翻译。选了哪家，才显示哪家的密钥输入框 —— 四个输入框全摆着是让人猜。

⚠️ 默认只生成、不覆盖。已经有别名 / 标签 / 摘要的字段不会被动，想让它改写要显式勾选。

· 引擎自己新建的标签带着标记，与人工打的标签可区分。词典不会把「引擎造的、又几乎没人用」的词当成已有标签复用到下一篇文章 —— 这一步是必要的：早先没有这个标记时，一次误建的 passwo、laoyang 会被后面每篇文章反复复用，垃圾越滚越多。

十一、访问统计面板

百度统计的数字直接显示在主题设置页里，不用再跳去他家网站看。

为什么要绕这一圈：主题自带的 views 字段只数「文章页被打开了几次」，数不出来源、设备、跳出率；自己在服务器上攒日志分析，PV 上万就开始拖页面，而且爬虫、自己刷的、预加载的全算进去。用现成统计服务是正解，只是数据在别人那儿 —— 所以补一步：拿它的「数据导出服务」把数字取回来。

怎么开（做一次就够）
1. 百度统计 → 管理 → 数据导出服务，开通后拿 API Key 和 Secret Key，填进对应两格。
2. 填站点 ID —— 网站列表点进站点后，地址栏 siteId= 后面那串数字。整条地址粘进去也行，会自动抠出数字。
3. 点面板里的「去授权」，用你自己的百度账号登录同意。会跳回你的网站并在地址栏带回 code=，把那一段粘进「授权码」保存。
4. 保存后立刻用这个 code 换 refresh_token，之后自动续期。授权码只能用一次，保存后那一格会自己清空 —— 再填一次是没用的，要重新走第 3 步。

面板上有什么：今日浏览量 / 访客数 / IP 数 / 新访客 / 访问次数（各带昨日同期对比，涨红跌绿）；跳出率、平均访问时长、平均访问页数；最近 7 天趋势柱状图；流量来源 / 热门页面 / 设备分布 / 地域分布四张榜单（各取前十）。

这十几项都能单独关掉。每勾一项就是一次 API 调用，百度配额按次计 —— 只看两三个数字的话，其余关掉能省不少。

几个特意做对的地方
· 没数据不是 0。百度接口对「这天还没数据」返回的是 "--"。直接转整数的话，面板会把「暂无数据」显示成「0 次访问」，看着像没人来，其实是还没统计出来。所以它渲染成一个灰色破折号，和真的 0 区分开。
· 不拖慢设置页。先出框、后取数：页面秒开，数字由 AJAX 补进来。同步取数的话，八个接口 × 每个 5 秒超时，最坏情况要卡 40 秒。
· 失败不卡死。取数成功缓存 30 分钟，失败只缓存 5 分钟 —— 接口临时挂了不会每刷新一次等一次超时，也不会因为一次失败要等半小时。
· 接口挂了不影响改设置。统计只是一个信息块，取不到就在那块里说「暂不可用」并给原因，上面所有设置照常能改能存。
· 密钥不进数据库。API Key / Secret / refresh_token 存在 wp-content/uploads/ 下一个独立文件（权限 600），不写进 options 表，也不在表单里回显。换主题、升级主题都不会丢。

十二、哀悼模式

到了设定的纪念日，整页最上方正中会出现一条哀悼提示条，其他日子完全不出现。

· 日期按节气逐年换算（清明这类），不是写死一个公历日子 —— 清明每年差一天，写死会错。
· 可以设持续天数。
· 只改提示条，不动全站配色。整站变灰那种做法，平时看惯了的读者会以为站挂了。

十三、页脚

版权行、ICP 备案号、公安备案号（带图标和链接）、站点旗帜图、建站天数。都能单独开关。

⚠️ 备案号里的链接必须指向工信部或公安部的官方查询页。填成自己的站内页，审核会被打回。

十四、自定义代码

最后一块兜底：「主题设置 → 自定义代码」，两格，一个放 CSS，一个放 JS。

· 加了会直接输出到全站，不做任何过滤（包括 JS）—— 能写就能跑，回头自己删。所以只往里放自己写的，别粘来路不明的代码。
· 优先级最高：这里的 CSS 在主题样式之后加载，能覆盖主题的任何规则。
· 页脚会额外输出一段按需加载的脚本，用于「只在某篇文章才需要」的那种小功能。

十五、几个常见问题

Q：装完之后页面样式是乱的 / 后台改设置没反应。
先清缓存。三层都要清：浏览器、CDN（如果开了）、以及服务器上的 OPcache。三层里任何一层留着旧文件，都会表现成「改了没用」，而文件本身明明是对的 —— 这种问题最难查。

Q：代码块不显示高亮，或者出现两个复制按钮。
九成是同时开了别的高亮插件（Enlighter、Prism、Code Prettify 之类）。主题自带一套完整的，把它们停掉。

Q：评论框里输入的东西消失了。
检查是不是装了两个评论增强插件，或者主题的评论模块被插件替换了。主题会在检测到第三方评论系统时让位 —— 如果两个都以为自己该画，就会互相覆盖。

Q：自动头像没生效。
三个原因按顺序查：① 后台没开；② 用户自己有 Gravatar 头像（主题尊重已有头像，不会顶掉）；③ 主题选项里设成了「只对评论生效」，而你正在看的是文章列表。

Q：目录里少了某些标题。
目录默认只收 h1/h2/h3。文章里用了 h4/h5 的话，要么在后台把 levels 调宽，要么在 [TOC] 里显式写 levels="1,2,3,4"。另外，标题必须是真正的标题元素 —— 用加粗大字冒充的 h3 不会被收进去。

Q：链接点了要跳走，能不能在新标签页开？
能。设置页说明文字里的那些外部链接（百度统计后台、robots.txt、翻译 API 等）都是新标签页打开，不会把你正在改的设置页顶掉 —— 改了一半的设置不会因此丢失。

十六、这个主题不做什么

说清楚边界，比列功能更有用。

· 不做页面构建器。它是给「写文章」用的，不是拖块拼页面的。要那套能力请用区块编辑器或专业构建器。
· 不做电商、会员、论坛。这些该用插件，主题不重复实现。
· 不接管全站性能优化。缓存、压缩、图片转 WebP 交给专业插件（或 CDN），主题只保证自己不拖后腿 —— 20 套代码配色只加载一套，就是出于这个。
· 不收集任何访客数据。自动头像在服务器端由主题自己生成，不把邮箱发给任何外部服务。统计走你自己配的百度统计。

十七、遇到问题

这个主题是本人在用、边用边改的，没有商业化发行，也没有工单系统之外的客服。
代码、改动记录、已知问题都在仓库里：
https://code.yangyq.net/laoyang/wordpress-kratos-yang

提问题之前，先说清三件事，能省一半来回：什么版本（后台首页能看到）、什么操作（点了哪里）、什么现象（截图 + 浏览器控制台的报错原文）。