跳到主要内容
Ed. notes

02 内容模型(一):为什么用 Markdown 而不是 CMS

长文 · 2026-11-10 · 合集第 3 / 12 篇

  • 构建日志
  • 内容模型
  • Markdown
  • Zod
第 3 / 12 篇 · 查看全部章节 → 当前:02 内容模型(一):为什么用 Markdown 而不是 CMS

02 内容模型(一):为什么用 Markdown 而不是 CMS

一句话结论:CMS 解决的是编辑体验,Markdown + schema 解决的是内容的所有权;对一个人的内容站,后者更便宜,也更耐用。

它解决什么问题

内容模型是站点最上游的决定。它看起来只是「文章存在哪里」,实际上决定了后面所有事情的成本:

  • 备份是 git clone,还是导数据库;
  • 迁移是换一个目录,还是换一套服务;
  • 部署要不要多一个数据库容器;
  • 写作是打开后台,还是打开编辑器;
  • 以后做 RAG,是直接读文件,还是先写一套导出接口。

CMS 能解决编辑体验:可视化编辑、草稿、定时发布、多人协作、媒体库。但它也带来一整套需要照看的东西:服务、数据库、账号、权限、备份、升级、插件和安全补丁。对一个人维护的内容站,这些成本很容易超过收益。

Markdown 则把内容还原成文件。文件可以 diff、可以回滚、可以 clone、可以备份、可以被任何编辑器打开,也可以被后续的 Agent 直接读取。代价是写作门槛:你得接受 Git 流程,接受没有可视化编辑器。

但 Markdown 本身不是内容模型。它只规定「正文怎么写」,不规定「一篇笔记需要哪些字段、日期是否合法、标签能不能重复、slug 怎么生成」。没有这些约束,内容积累到几十篇就会开始腐烂:有人写 type: blog,有人写 type: 博客;有人把日期写成 2026/11/08;有人复制一篇旧笔记忘了改 slug。

所以我需要的不只是 Markdown,而是一份可执行的契约:人写 frontmatter,构建时用 schema 校验,错了就阻止发布。

我怎么试的

1. 先定目录和 slug,而不是先写页面

content/
  notes/
    pydantic-ai.md              # 单文件笔记,slug = pydantic-ai
    rag-minimal-loop/           # 带本地图片的笔记用目录形式
      index.md                  # slug = rag-minimal-loop
      cover.png
  articles/
    01-从0建小站/                   # 博客实现路径,按系列编号组织

slug 由文件名或目录名决定,不写在 frontmatter 里。理由有三个:

  • slug 只出现一次,不会出现「文件名是 A、frontmatter 里写 B」的冲突;
  • URL 和文件系统一一对应,迁移时不需要额外映射;
  • 强制 slug 使用小写 kebab-case,避免中文、空格和大写带来的转义问题。

带本地图片的笔记用目录形式,图片和 index.md 放在一起。这样一篇笔记就是一个可以整体移动、整体备份的单元。

2. 把 frontmatter 写成 schema

一篇笔记的开头长这样:

---
title: 'Pydantic AI:让 Agent 的输出有据可依'
summary: '先定义输出结构,再设计工具调用;类型约束不能消除幻觉,但能让失败更早暴露。'
type: tool
date: 2026-11-08
tags: ['智能体', 'Python', '类型安全']
repo: 'https://github.com/pydantic/pydantic-ai'
series: 'build-log'
draft: false
---

字段不多,但每一条都有明确约束:

字段 必填 约束
title 是 非空字符串
summary 是 非空,用于卡片和 SEO 描述
type 是 只能是 tool、repo、experiment
date 是 YYYY-MM-DD,且必须是真实存在的日期
tags 是 至少一个,不能重复
series 否 系列名,例如 build-log
repo / website 否 必须是有效 URL
draft 否 默认 false

真正把这套约束固定下来的是 Zod:

const frontmatterSchema = z
  .object({
    title: z.string().trim().min(1, '标题不能为空'),
    summary: z.string().trim().min(1, '摘要不能为空'),
    type: z.enum(['tool', 'repo', 'experiment']),
    date: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, '日期格式必须是 YYYY-MM-DD')
      .refine(isValidDate, '日期不是有效日期'),
    tags: z
      .array(z.string().trim().min(1))
      .min(1, '至少需要一个标签')
      .refine((tags) => new Set(tags).size === tags.length, '标签不能重复'),
    series: z.string().trim().min(1).optional(),
    repo: z.string().url().optional(),
    website: z.string().url().optional(),
    draft: z.boolean().optional(),
  })
  .strict()

isValidDate 不是简单看格式,而是用 Date.UTC 反查年月日,防止 2026-02-30 这种「格式对、日期不存在」的值混过去。

最后那个 .strict() 很重要:未知字段会被拒绝。这样 tgas、summry 这类拼写错误会在构建时暴露,而不是悄悄变成一个没人读的字段。代价是新增字段时必须同步改 schema,不能靠「先加上再说」。

3. 构建前校验,而不是发布前自觉

校验脚本挂在 prebuild 上:

"prebuild": "node scripts/validate-content.mjs",
"content:validate": "node scripts/validate-content.mjs"

写这篇文章时,content/notes/ 还是空的,所以单独跑校验会得到:

$ npm run content:validate
内容校验通过:0 篇笔记,其中 0 篇草稿。

这个 0 不是失败,而是我刻意选择的顺序:先把管线和约束做好,再往里放内容。 这样第一批笔记写进来时,格式问题会立刻暴露,而不是等积累了几十篇再返工。

我又拿两份故意写坏的文件跑了一次:

内容校验失败(5 项):
- notes/2026-02-30.md: date: 日期不是有效日期
- notes/broken.md: title: 标题不能为空
- notes/broken.md: type: 类型必须是 tool、repo 或 experiment
- notes/broken.md: date: 日期不是有效日期
- notes/broken.md: tags: 至少需要一个标签

一次列出所有问题,每条都带文件路径。构建会在这里停下,不会把坏内容带到线上。

4. 一个真实的坑:YAML 会把非法日期滚成另一天

这段输出是修完之后的。修之前,同样的两份文件只报了 3 项,而且两条日期错误都不见了。

原因不在 Zod,在 YAML。默认的 YAML schema 会把未加引号的日期解析成 Date:

2026-13-40  =>  2027-02-09T00:00:00.000Z (Date)
2026-02-30  =>  2026-03-02T00:00:00.000Z (Date)
2026-11-08  =>  2026-11-08T00:00:00.000Z (Date)

2026-02-30 不存在,但它被悄悄滚到了 3 月 2 日。我第一版的做法是「如果是 Date,就转回 ISO 字符串再校验」,结果校验器看到的是 2026-03-02——一个完全合法的日期。解析器把错误吃掉了,校验器再严格也没用。

更隐蔽的是测试。我的测试数据是用 matter.stringify 生成的,它会给日期加引号,所以日期一直是字符串,测试全绿;手写笔记里没人给日期加引号,问题就漏了。

修复方式是不让 YAML 决定类型:

parsed = matter(source, {
  engines: {
    yaml: {
      parse: (input) => loadYaml(input, { schema: JSON_SCHEMA }) as Record<string, unknown>,
    },
  },
})

JSON_SCHEMA 让日期保持字符串,是否合法交给 Zod 的 isValidDate。然后我补了一条用手写 YAML(日期不加引号)的测试,专门覆盖这个场景。现在 110 个测试全过。

这件事给我的教训不是「YAML 有坑」,而是:测试数据要覆盖真实写法,而不是测试工具生成的写法。 工具会帮你把边角磨平,真实输入不会。

坑和限制

1. 日期类型是隐式的。 不止 YAML,CSV、JSON、环境变量都有类似的自动类型转换。任何「看起来是字符串」的字段,都要确认解析器没有提前改过它。

2. .strict() 是双刃剑。 它能抓住拼写错误,也意味着每次加字段都要改 schema、改文档、改测试。对一个人项目值得;如果字段经常由非开发者提出,可能会变成摩擦。

3. slug 是 URL,不是文件名。 改文件名会改 URL,旧链接会断。写之前想清楚,写完之后尽量别改;真要改,就加重定向。

4. 标签是自由文本。 现在没有标签白名单,AI、ai、人工智能 会被当成三个标签。内容少的时候问题不大,数量上来后需要规范化或白名单。

5. Markdown 的 HTML 是关掉的。 html: false 能避免把不可信 HTML 直接渲染进页面,代价是不能在正文里塞 iframe、自定义组件或复杂布局。需要时再引入受控的 shortcode,而不是放开原始 HTML。

6. 没有可视化编辑器。 手机上改一篇笔记很别扭,预览也要靠本地开发服务器。这是选择 Git 的代价;如果以后真的需要,可以加一个 Git-based 编辑器,内容仍然留在仓库里。

7. schema 管不了质量。 它能保证字段齐全、日期合法,但保证不了「这篇有没有个人实验」「结论是不是自己的」。后者只能靠写作规则和发布前检查。

8. CMS 仍然适合另一类人。 如果作者不是开发者,或者需要多人协作、角色权限、评论和媒体库,CMS 的编辑体验会明显更省事。这不是「CMS 不好」,是场景不同。

适合谁

如果你自己写内容、自己维护站点,并且能接受 Git 的工作流,Markdown + schema 这套东西很划算:备份就是 clone,迁移就是复制目录,内容还能直接喂给后面的 RAG。

如果你打算长期写,但不想被某个平台锁定,这套模型也适合。内容在文件里,换框架、换部署、换域名都不会丢。

它不太适合这几类人:作者不是开发者、需要可视化编辑的;多人协作、需要角色和评论的;希望「开箱即用、不碰服务器」的;以及内容字段经常变化、又不想维护 schema 的。

下一篇是 03 内容模型(二):从 Markdown 到 API。frontmatter 只是契约,真正让内容变成站点的是加载、草稿过滤、标签与系列聚合、图片路径,以及两条返回 JSON 的接口。

继续探索