Frontmatter 参考

Frontmatter 位于 Markdown 或 MDX 文件顶部。通用页面字段适用于全部内容；hero 和 features 只用于各语言首页。

未知字段可以被解析，但不影响 Canofold 行为，也不会自动写入公开 AI 索引。ai/pages.json 仅保留 title、description、createdAt、updatedAt、order、group、subgroup、tags 和 owner。

通用页面字段

普通内容页通常只需要标题、描述和排序：

yaml

---title: API 鉴权seoTitle: API 鉴权与请求签名｜Acme Docsdescription: 配置服务端 API Token 和请求签名order: 20---


`title`	`string`	第一个标题或空	页面标题、侧栏和默认 SEO title
`seoTitle`	`string`	由 `title` 和站点标题生成	仅覆盖浏览器与搜索结果标题，不改变页面标题、侧栏、搜索或 AI 数据
`description`	`string`	空	SEO、搜索结果和确定性摘要
`createdAt`	ISO 8601 日期	无	保存内容创建时间并写入公开页面元数据
`updatedAt`	ISO 8601 日期	可确认的 Git 内容提交时间；否则不显示	固定页脚“最后更新”时间并写入公开页面元数据
`group`	`string`	一级目录名	顶级分区的兼容/显示覆盖字段
`subgroup`	`string`	二级目录名	第一层嵌套分组的兼容/显示覆盖字段
`order`	`number`	最后	页面、侧栏和上下篇顺序
`collapsed`	`boolean`	`false`	目录 `index.md` 对应分组的初始折叠状态
`layout`	`document \| playground`	`document`	使用标准文档布局，或为可编辑源码/预览页启用 Playground 布局
`status`	`published \| draft`	`published`	草稿可在 `dev` 预览和 `check` 检查，不进入生产构建
`sidebar`	`boolean`	`true`	是否出现在侧栏，不影响路由生成
`search`	`boolean`	`true`	是否进入搜索索引
`ai`	`boolean`	`true`	是否进入 AI 输出
`tags`	`string[]`	空	写入 `ai/pages.json`
`owner`	`string`	空	写入 `ai/pages.json`
`translation.sourceHash`	`sha256:<64 位十六进制>`	无	译文复核时对应的默认语言源页内容指纹，仅用于 `check`；未填写时状态为“未知”

本地 dev 可以预览草稿首页；发布前，每个版本和语言仍必须有已发布的首页。若首页仅有 status: draft，check 和正式构建都会失败。

导航字段

各级目录的 index.md 是分组名称和折叠状态的权威来源。同一目录声明不同的 group 或 subgroup 会使构建失败。

group 和 subgroup 不会把内容树限制为两层。递归导航应使用各级目录的 index.md；这两个字段主要用于兼容旧内容或覆盖显示名称。

日期字段

需要明确指定更新时间时填写 updatedAt。日期使用 YYYY-MM-DD，带时间时必须包含 Z 或 +08:00 这样的时区偏移。未填写时，Canofold 使用完整 Git 历史中该文件最近一次内容提交的时间；工作区文件未提交、仓库为浅克隆或无法获取 Git 历史时，不显示“最后更新”，不会以检出时间或浅克隆边界提交的时间冒充内容更新时间。需要在 CI 中显示 Git 日期时，应检出完整历史（例如 GitHub Actions 的 actions/checkout 配置 fetch-depth: 0），或显式填写 updatedAt。

译文复核指纹

翻译完成并与默认语言源页核对后，运行 canofold check --json，从 translationStatus 中找到目标语言页面的 sourceHash，将它写入该译文的 translation.sourceHash。之后源页标题、描述或正文改变，check 会报告译文过期。未记录指纹或缺少源页时显示 unknown，不会根据文件时间推断译文是否过期。重新复核译文后再更新指纹；不要只为消除告警而复制新值。

首页字段

每种语言的首页都由该语言根目录的 index.md 配置。默认语言使用 docs/index.md，其他语言使用 docs/{locale}/index.md。canofold.config.ts 只保存站点级配置，不保存首页文案。

yaml

---title: Acme DocsseoTitle: Acme Docs｜从接口定义生成可部署的文档站hero:  accent: 从接口定义生成可部署的文档站  tagline: 在仓库中维护内容和配置，构建结果可以直接部署。  image: /banner.png  imageAlt: Acme 文档构建流程  actions:    - text: 快速开始      link: /guide/getting-started/      primary: true      icon: rocketfeatures:  - image: /feature/api.png    title: 接口参考    details: 从版本化内容生成可搜索的接口文档。---

页面结构


`title`	`string`	Hero 主标题	首页唯一的可见主标题
`seoTitle`	`string`	不直接显示	仅覆盖浏览器与搜索结果标题；适合为简短品牌名补充产品定义
`description`	`string`	不直接显示	SEO description 和搜索摘要
`hero.accent`	`string`	主标题下方	一句话说明首页的核心信息
`hero.tagline`	`string`	Accent 下方	用一到两句话补充产品定义或使用范围
`hero.image`	`string`	Hero 右侧	首页主视觉；省略后使用单栏布局
`hero.imageAlt`	`string`	不直接显示	图片的替代文本；纯装饰图片可写空字符串
`hero.actions`	`array`	Hero 按钮组	按数组顺序从左到右显示
`features`	`array`	Hero 下方	首页能力卡片

hero.image 和 actions[].link 接受以 / 开头的站内路径或 HTTPS URL。其他协议会使检查和构建失败。

Hero 按钮


`text`	`string`	是	按钮文案
`link`	`string`	是	站内绝对路径或 HTTPS URL
`primary`	`boolean`	否	使用主按钮样式；一个首页最多设置一个
`icon`	`string`	否	使用 Canofold 内置 Lucide 图标

能力卡片


`title`	`string`	是	卡片标题
`details`	`string`	是	一句能力说明
`image`	`string`	否	使用 `{docsDir}/public/` 中的图片，例如 `/feature/api.svg`
`icon`	`string`	否	使用与按钮相同的内置图标

同时填写 image 和 icon 时优先显示 image；两者都省略时显示纯文本卡片。

图片与内置图标

以 / 开头的图片路径映射到 {docsDir}/public/。例如 /banner.png 对应 {docsDir}/public/banner.png，/feature/api.svg 对应 {docsDir}/public/feature/api.svg。

按钮和能力卡片也可以使用 Canofold 内置的 Lucide 图标，不需要安装图标包。可用值为 ai、box、code、file、file-code、gauge、globe、layers、rocket、search、sparkles 和 terminal。

首页字段会在内容扫描阶段校验。类型错误、未知子字段、不支持的图标或多个主按钮都会使检查和构建失败。