内容编译器
一个两百行的零依赖脚本,把手写 Markdown 变成页面数据。
需求小到不值得引入一个库。
这个站点需要把手写的 Markdown 源文件编译成页面数据。看起来是个标准需求,装一个成熟的 Markdown 解析器就能解决——但真正需要的只是「读 frontmatter、按空行分段、认几个前缀标记」,而任何一个通用解析器都会带来远超这个需求的表面积。
所以它是自己写的。frontmatter 解析器只支持两种形式:单行的键值对,和缩进的块列表。不支持嵌套对象、不支持多行字符串、不支持行内数组。值不要带引号——因为解析器不处理引号。
这个限制清单看起来像缺陷,实际上是这个工具最有价值的部分。每一条「不支持」都是一次明确的拒绝:拒绝把需求扩大到当前用不上的地方。文档里把它们逐条写出来,而不是留给使用者去试错。
报错比功能更值得投入
这个脚本里花心思最多的地方不是解析,是报错。指针指向不存在的条目、双向互指只写了一边、小节标题后面的段落太短会导致渲染错位——每一种情况都有专门的检查,并且报错信息里带文件名、带错在哪、带该怎么改。
原因很简单:这个工具唯一的使用者是我自己,而我半年后会忘记所有隐性约定。一条说清楚的报错,比一页写得再好的文档都管用,因为它在真正需要的那一刻主动出现,而文档需要你想起来去查。
什么时候该换掉它
如果有一天需要嵌套结构、需要行内富文本、或者需要多个人协作填内容,那就是这个脚本该退休的信号。到那时换一个成熟方案是正确的决定,而不是继续在一个为单人单用途写的东西上打补丁,把它慢慢喂成一个四不像。
在那之前,两百行零依赖的代码,比一个我只用到百分之三功能的库更容易理解、更容易改、也更容易丢掉。
