第 4 篇：内容即数据——frontmatter 规范、数据结构与构建链路的工程化设计

📌 本篇核心目标：建立"内容文件不是文本，而是系统输入"的工程化思维。掌握 frontmatter 字段设计方法论、slug 规则、分类标签治理策略、核心实体的 schema 设计，以及从内容到页面的完整构建链路。

这篇为什么是整本小册最重要的一篇

前三篇教你搭了两层东西：

• 第 2 篇：CLAUDE.md 主文件（规则入口）
• 第 3 篇：docs/ 文档体系（专项细则）

但如果这些文档里的内容质量不高——规则写得不准、字段设计有漏洞、数据链路没理清——那整套体系就是个空架子。

这篇讲的是"往架子里填什么"。

具体来说，它回答三个问题：

1. 内容文件的 frontmatter 应该怎么设计，才能稳定、可维护、不被 Claude 搞乱？
2. 项目的数据实体和字段关系应该怎么梳理，才能在结构变更时有据可查？
3. 从 content/ 目录到最终页面的构建链路是什么样的，Claude 需要理解到什么程度？

这三个问题的答案，直接决定了你的 docs/content-rules.md、docs/data-schema.md 和 docs/build-process.md 写得好不好。

也直接决定了 Claude 在你的内容项目中犯错频率是高还是低。

第一个认知转变：内容文件不是文本

你打开 content/articles/teacher-cert-guide.md，看到的是这样的东西：

---
title: 2026年教师资格证报考完整指南
description: 从报名条件到考试科目，一文搞懂教资报考全流程
slug: teacher-cert-guide
category: 备考指南
tags: [教师资格证, 报考流程, 2026]
date: 2026-01-15
draft: false
---

# 2026年教师资格证报考完整指南

教师资格证考试是……

看起来就是一篇 Markdown 文章，对吧？

但从系统的角度看，它同时是 8 个东西：

这篇 Markdown 文件，同时是：

1. 详情页的数据源       → title、description、content 被渲染成详情页
2. 列表页的一个条目      → title、description、date 出现在文章列表里
3. 分类聚合页的成员      → category="备考指南" 让它出现在"备考指南"分类页
4. 标签聚合页的成员      → tags 让它出现在"教师资格证"等标签页
5. 搜索索引的一条记录    → title、description、tags、content 被写入搜索数据
6. 路由系统的一个映射    → slug="teacher-cert-guide" 决定 URL 是 /teacher-cert-guide
7. SEO 的元数据来源     → title 和 description 影响搜索引擎收录
8. 内链和推荐的被引用对象 → 其他文章的 related_articles 可能引用它的 slug

Claude 默认不知道这些。

它看到一个 Markdown 文件，只会把它当"一篇文本"来处理。你让它"改个分类"，它就改了——不会想到这个改动还影响分类聚合页。你让它"优化一下 slug"，它就改了——不会想到旧 URL 会 404、搜索引擎已收录的链接会失效。

你的 docs/content-rules.md、docs/data-schema.md 和 docs/build-process.md 的核心任务，就是把这些"隐性连锁关系"变成"Claude 能看到的显性规则"。

下面一个模块一个模块来讲。

Frontmatter 设计方法论

Frontmatter 是内容文件的"头部元数据"，是整个内容系统的数据基础。它设计得好不好，直接决定了你的内容系统是"越用越稳"还是"越用越乱"。

设计原则：稳定性 > 完整性

很多人设计 frontmatter 的思路是"我需要什么字段就加什么字段"。结果三个月后，不同时期新增的内容文件，frontmatter 五花八门——有的有 summary，有的没有；有的用 author，有的用 writer；有的 tags 是数组，有的是逗号分隔的字符串。

正确的设计思路是：先定一套稳定的基础字段，所有内容文件严格遵守。扩展字段只在确认被消费后才启用。

"稳定"的意思是：

• 字段名不变
• 字段类型不变
• 字段语义不变
• 是否必填不变

一旦某个字段进入了"基础字段"清单，就不要轻易改动它。因为改动一个基础字段，意味着你需要同时更新：所有内容文件、类型定义、解析函数、页面模板、搜索索引脚本——任何一个环节遗漏，都会出问题。

基础字段：你必须有的 7 个

不管你的项目多大多小，以下 7 个字段基本是内容型知识库项目的标配：

---
title:""          # 页面标题
description:""    # 内容摘要
slug:""           # 唯一访问标识
category:""       # 主分类
tags:[]           # 标签数组
date:""           # 发布时间
draft:false       # 是否草稿
---

逐个说明为什么这 7 个是必备的：

title

最基础的字段，没什么争议。用于详情页标题、列表页展示、SEO 标题、搜索索引。

唯一需要注意的是：title 是"给人看的标题"，不是文件名。文件名用 slug 风格（小写英文+中划线），title 用自然语言。

description

内容摘要。用于列表页卡片、SEO meta description、搜索结果的展示片段。

很多人在早期会省略这个字段，结果列表页的摘要显示要么是空的，要么是用正文前 100 字截取的——效果很差。

建议：description 设为必填，长度控制在 50-150 字之间。

slug

整个 frontmatter 中最关键的字段，没有之一。它决定了页面的 URL，是内容在整个系统中的"身份证"。

后面会专门用一整节来讲 slug 规则。

category

主分类。每篇内容只属于一个 category。用于导航、分类聚合页、侧边栏分组。

category 和 tags 的区别后面会详细讲。

tags

标签数组。用于横向关联、搜索过滤、相关推荐。

注意 tags 必须是数组格式（tags: [标签A, 标签B]），不要用逗号分隔的字符串。统一格式能避免解析问题。

date

发布时间。用于排序、时间线展示、"最新内容"功能。

格式建议统一为 YYYY-MM-DD。不要有的文件用 2026-01-15，有的用 2026/01/15，有的用 Jan 15, 2026。格式不一致会导致排序出错。

draft

是否为草稿。draft: true 的内容不应该出现在正式的列表页、搜索索引和聚合页中。

这个字段看起来简单，但它的影响范围很大——构建脚本、搜索索引、列表查询、RSS 生成，所有环节都需要正确过滤草稿。一旦过滤逻辑有漏洞，草稿内容就会被公开发布。

扩展字段：怎么判断该不该加