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

本篇核心目标建立内容文件不是文本而是系统输入的工程化思维。掌握 frontmatter 字段设计方法论、slug 规则、分类标签治理策略、核心实体的 schema 设计以及从内容到页面的完整构建链路。这篇为什么是整本小册最重要的一篇前三篇教你搭了两层东西第 2 篇CLAUDE.md 主文件规则入口第 3 篇docs/ 文档体系专项细则但如果这些文档里的内容质量不高——规则写得不准、字段设计有漏洞、数据链路没理清——那整套体系就是个空架子。这篇讲的是往架子里填什么。具体来说它回答三个问题内容文件的 frontmatter 应该怎么设计才能稳定、可维护、不被 Claude 搞乱项目的数据实体和字段关系应该怎么梳理才能在结构变更时有据可查从 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. 路由系统的一个映射 → slugteacher-cert-guide 决定 URL 是 /teacher-cert-guide 7. SEO 的元数据来源 → title 和 description 影响搜索引擎收录 8. 内链和推荐的被引用对象 → 其他文章的 related_articles 可能引用它的 slugClaude 默认不知道这些。它看到一个 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 生成所有环节都需要正确过滤草稿。一旦过滤逻辑有漏洞草稿内容就会被公开发布。扩展字段怎么判断该不该加