对博客主题来说,配置是「给开发者的选项」;对机构官网主题来说,配置文件就是客户的操作手册。60+ 项配置写得乱,客户就改不动;改不动,就要来找你。
这一篇讲这套配置怎么分组、怎么保证升级不丢、以及踩到的 YAML 坑。
一、分组原则:按页面区域,不按技术模块
_config.yml 的一级键顺序,就是页面从上到下的顺序:
1 | preset: enterprise # ① 整体气质 |
客户想改「页脚的备案号」,他会去页面底部找,然后来配置里找——如果分组是按技术模块分的(i18n / components / utils),他就找不到。
判据:客户看着页面能不能猜到配置在哪一节?
二、每个板块都遵循同一套结构
1 | services: |
四段式:开关 / 文案 / 数据 / (可选)跳转。所有 12 个板块都是这个结构,客户学会一个就会用全部。
早期我把「是否显示」和「显示什么」混在一起——不填标题就隐藏。结果是客户清空标题想临时隐藏,却发现布局塌了。
现在 enable 是唯一开关,文案为空只影响文案本身,布局不受影响。
三、升级不丢配置:站点覆盖文件
这是 Hexo 自带但很多人不知道的机制:站点根目录放 _config.<主题名>.yml,Hexo 会自动把它与主题 _config.yml 深度合并。
1 | my-site/ |
1 | # _config.hexo-theme-xongyi.yml |
好处有三:
- 只写差异:不用复制整份主题配置,行数少;
- 升级不丢:主题用 git submodule 引入,
git submodule update不会动站点根目录的文件; - 一眼看见定制了什么:改过哪些默认值清清楚楚。
是 _config.hexo-theme-xongyi.yml,不是 _config.xongyi.yml。主题目录叫什么,文件名就叫什么——这也是我在第八篇讲的「仓库形态改造」里强调目录命名要遵循官方规范的原因之一。
四、预设示例:给客户一个能抄的起点
光有配置项还不够,客户需要「政务站长什么样」。所以提供完整的示例配置:
1 | examples/ |
客户最难的往往不是填参数,而是不知道该写什么文案。示例里给出「办事指南」「信息公开」「在线咨询」这类行业化措辞,比给一组占位符有用得多。
五、YAML 的两个坑
坑 1:双引号字符串里不能再嵌 ASCII 双引号
1 | # ❌ 解析失败 |
政务示例的文案里大量出现引号,统一改用『』。
坑 2:注释里的配置项要跟着代码更新
配置文件的注释就是文档。我给自己定的规则是:改了模板逻辑,必须同步改 _config.yml 对应注释和 README。
三个「文档与实物不一致」的典型
- 新增了板块但没在
sections注释里的「可用板块」清单中列出 → 客户不知道有这个板块; - 改了默认值但注释里还是旧值 → 客户按注释填,结果不对;
- README 的特性表加了功能,但配置里没这个键 → 客户照着 README 找不到。
修法:写文档时对着 _config.yml 逐项念一遍,而不是凭记忆写。
六、配置项的取舍:什么时候拒绝加配置
有客户要求「每个板块的背景色单独可配」。我拒绝了。
理由:加一个 background 键,就要处理「配置了但和预设冲突怎么办」「暗色模式下这个颜色怎么变」,然后预设机制被撕开一个口子。
- 这个需求在 10 个客户里有几个会用到?
- 加了它,会不会和既有机制(如预设、暗色模式)冲突?
- 客户能不能用已有能力(自定义 CSS)解决?
三个问题里有两个答不好,就不加。配置表膨胀是慢性病,一旦失控就很难收回。
系列导航
xongyi 系列总入口 · 上一篇:首页板块系统 · 下一篇:内容建模
评论