上一篇讲了三条产线怎么分工。这一篇往里钻一层:
这三条线之间传递的到底是什么数据,它由谁说了算。
一、三层模型
先把三个容易混的词分清楚。
母稿 —— 作者写的那份 markdown,躺在 docs/ 目录里。
它只表达「这篇文章是什么」,不表达「它长什么样」。
内容单元 —— 编译之后的产物,落在 source/_posts/ 下。
它是母稿加上构建期推导出来的东西:分类、标签、日期、
图片路径改写过的正文、以及一份重建过的前置元数据。
平台产物 —— 公众号里的那篇推文、头条上那个排版包、B 站的投稿包。
它是从内容单元再派生一层的结果。
为什么要多这一层?直接拿 docs/ 里的文件发到平台不行吗?
不行,因为有三个东西只有构建期才知道:
- 分类名。目录是英文的,分类名是中文的——中文名写在分类索引文件里,
在构建期被解析出来。平台侧拿不到「这条内容属于哪个中文分类」。 - 发布日期。全站文章的日期不是作者填的,是从 git 历史里取最早一次提交时间。
这个时间在构建期算出来,写进产物。平台侧要拿它排期。 - 站内链接与图片路径。站内链接要改写成能点的绝对地址,
图片要改写成构建产物里的相对路径。这一步必须发生在编译期,
因为只有那时才知道最终 URL 长什么样。
还有一个更重要的理由:内容单元是「一份内容」的稳定身份。
它的路径就是内容的标识,所有下游——发布清单、幂等键、
站点的跨平台索引——都拿这个标识做主键。
有了它,「这篇文章发到哪几个平台」才有地方记。
二、契约:谁能写什么
内容契约规定的是前置元数据(front matter)的字段表。
字段分两类,分工非常清楚。
推导字段:机器说了算
| 字段 | 从哪来 |
|---|---|
date |
该路径在所有分支上的最早提交时间;作者显式写 date: 可以覆盖 |
categories |
目录索引文件里的中文分类名 + 祖先目录的级联分类,去重 |
tags |
分类 + 从路径与标题推断出的主题词 |
author |
固定值 |
作者写了也会被覆盖。这不是霸道,是因为这些字段必须全局一致:
如果每篇文章自己写分类,迟早会出现两篇同名文章归到不同分类,
分类页就会漏掉一半。日期同理——它是排序依据,
如果一部分文章手填日期、一部分自动生成,「最近发布」就会乱。
透传字段:作者说了算
| 字段 | 类型 | 约束 | 送达哪里 |
|---|---|---|---|
title |
字符串 | ≤ 80 字 | 文章标题 |
short_title |
字符串 | ≤ 32 字 | 公众号 / 头条的短标题 |
tldr |
字符串 | ≤ 120 字 | 文章顶部的 TL;DR 区块 |
description |
字符串 | ≤ 150 字 | 摘要、分享卡片 |
difficulty |
整数 | 1–5 | 难度星级 |
cover |
字符串 | 相对文章目录 | 封面图 |
reprintPolicy |
枚举 | 主题支持的转载声明 | 版权声明区块 |
kind |
字符串 | post / video |
内容单元类型 |
platforms |
字符串列表 | 平台标识 | 发布候选集 |
publish_on |
字符串 | YYYY-MM-DD |
指定发布日期 |
白名单一共 19 项:上面这 10 项是文章用的,另外 9 项
(episode、episode_no、series、episode_hook、episode_subtitle、episode_duration_s、episode_license、episode_sources、episode_repro)
是视频期号专用的。
同一份契约要同时管住文章和视频两类内容单元,
所以白名单是「文章字段 + 视频字段」,不是只有文章字段。
透传的意思是:作者写了什么,编译时原样搬过去,一个字都不改。
包括值不合法的时候也照搬——校验归契约层管。
在这里悄悄丢掉更糟:丢了等于「这篇不发」,
而作者以为自己写了。
这里有个细节值得单独说:
description是一份内容、多个平台共用的摘要来源。
在它存在之前,每篇文章的分享预览文案都是同一句站点简介——
分享到微信、B 站、头条,预览里全是同一句话。
一个字段把这个问题解决了。
三、为什么是白名单,不是全文转储
契约层拿到母稿的前置元数据后,只保留白名单里声明过的字段,
其余顶层字段一律丢弃。
这是整套设计里最容易被质疑、也最值得坚持的一条。
「为什么不直接把整个前置元数据搬过去?」——因为前置元数据里迟早会出现
一些只对某一处有意义的东西:一次性的草稿标记、给某个脚本看的临时参数、
某个工具的私有配置。这些字段一旦被原样搬进最终产物,
就会顺着发布链路流到平台上,流进搜索引擎索引里,
最后变成「文章页面带着一堆没人认得的属性」。
更麻烦的是,没人知道它在那儿。白名单的价值不在于省几行字符,
而在于它让「产物里有什么」这个问题有确定答案:
表里有就一定在,表里没有就一定不在。
代价是每加一个字段要改一次表。这个代价是值得的——
表的改动会触发评审,而「顺手在文章里加个 key」不会。
四、格式规则:故意做得很土
契约规定前置元数据只允许两种形态:
- 扁平的
key: value - 单层的
key:换行后跟若干- item
嵌套只允许 cascade:(分类索引文件专用),多行值不支持。
为什么不用真正的 YAML?
因为上游没有 YAML 解析器。编译脚本切前置元数据用的是正则,
全站几百个文件里唯一用到的嵌套就是分类索引里的 cascade。
契约层如果允许完整 YAML,就得引入一个 YAML 依赖,
还得处理「解析器行为不一致」这一类最难查的问题——
同一段文本,两套解析器给出两个答案,产物就分裂了。
所以契约层自己写了一个极小的解析器,语义按 YAML 的真实规则走,
并且用测试把每一处差异显式钉住,而不是靠默契。
这里有两处刻意的分歧:一处是行尾符(CRLF)的处理,
一处是「键下面缩进了一个标量」该读成什么。
两处都写进了文档、都有对应的用例钉住。
这套格式不是新发明的:公众号那套适配器里早就有一份同样的解析器,
契约层是照着它的行为写的,然后加了两条一致性测试锁住两边不漂移。
五、一篇母稿,六种形态
同一份母稿到了不同平台,会变成完全不同的东西:
| 平台 | 形态 | 谁在裁 | 依据 |
|---|---|---|---|
| 网站 | 完整正文 + 分类 + 标签 + 封面 + 版权声明 | 编译期 | 推导字段 + 透传字段 |
| 公众号 | 图文,标题 ≤ 64 字,摘要 ≤ 120 字 | 平台适配器 | 平台能力声明的限额 |
| 头条号 | 头条版排版,标题 ≤ 30 字,正文图 ≤ 3 张,链接降级 | 平台适配器 | 平台能力声明的限额 |
| 抖音 | 竖版短视频,标题 ≤ 30 字,描述 ≤ 500 字,竖封面 3:4 | 平台适配器 | 平台能力声明的限额 |
| 视频号 | 竖版视频,标题 ≤ 16 字 | 平台适配器 | 平台能力声明的限额 |
| B 站 | 投稿包 + 字幕文件,标题 ≤ 79 字 | 平台适配器 | 投稿格式要求 |
注意一件事:作者只写一次文案。
每个平台上的标题裁剪、正文精简、配图取舍,全部由适配器按该平台的能力声明去做。
作者不需要为五个平台各写一版稿子——这正是「母稿唯一」这条不变量的直接收益。
六、几条踩出来的规矩
白名单透传,不做全文转储。 已在上面说过。
超限要留痕,不能悄悄砍。 标题超限时:写了 short_title 而它超限,
直接跳过并记录原因——截出来的标题对读者没有意义,
而且它把「这条内容不适合这个平台」这件事给掩盖了;
没写 short_title 就按上限裁剪,并记下「已裁剪」。
正文超限同样裁,但把「正文超过 N 字,已截断」写进这次发布的记录里。
没有一处是静默的。
约定俗成的东西要能被机器检查。 「约定俗成」是内容治理里最危险的一类规则——
因为它靠人记。人记不住的那天,规则就失效了,而且失效得很安静。
契约层不认识任何平台。 这条在上一篇讲过分层,这里再强调一次,
因为它是内容模型能独立演化的前提。