Frontmatter 用法与规范

iflux-next 项目包含两个内容站点：blog（技术博客）和 docs（文档中心）。它们共享同一套内容引擎 @iflux/utils，但在 Frontmatter 字段、文件组织和侧边栏配置上各有差异。

这篇文章系统梳理两者的规范，方便后续写作时直接参考。

一、Frontmatter 基础

Frontmatter 是 Markdown/MDX 文件顶部的 YAML 元数据区域，用 --- 包裹，用于定义文章的标题、日期、分类等信息。

---
title: 文章标题
excerpt: 文章摘要
category: 分类名
tags: [标签1, 标签2]
date: "2026-04-26"
---

两个站点的内容目录位于各自的 src/content/ 下，支持 .mdx 格式。构建时通过 gray-matter 解析 Frontmatter，并通过 @iflux/utils 的 Zod Schema 进行校验。

二、Blog 站点

文件组织

Blog 的文章统一放在 src/content/posts/ 目录下，每个 .mdx 文件即一篇文章，文件名即为 slug：

src/content/posts/ ├── frontmatter-guide.mdx ├── wsl2-arch-install.mdx └── ...

访问路径为 /posts/<slug>，例如 /posts/frontmatter-guide。

Frontmatter 字段

Blog 的 Frontmatter 通过 PostFrontmatterSchema 进行 Zod 校验：

字段详解

title

文章标题，显示在文章详情页、列表卡片和浏览器标签栏中。同时作为 SEO 的 <title> 和 Open Graph 标题。为空时降级为文件名（slug）。

date

控制文章在列表中的排序（新文章在前）。推荐加引号以避免 YAML 将日期解析为对象：

date: "2026-04-26"

description

SEO 描述字段，对应 HTML 中的 <meta name="description">，影响搜索引擎摘要显示。建议控制在 150 字符以内：

description: 在 WSL2 中安装 Arch Linux 的完整步骤，包括系统初始化、镜像源配置和开发环境搭建。

excerpt

文章摘要，显示在文章列表卡片中。与 description 的区别：excerpt 是面向读者的内容预览，description 是面向搜索引擎的 SEO 描述。两者可以写不同的内容。

category

文章分类，用于侧边栏筛选和文章归类：

category: 开发

tags

标签用于文章筛选，侧边栏会展示所有标签及其文章数量。两种写法等价：

tags: [标签1, 标签2, 标签3]

tags:
  - 标签1
  - 标签2
  - 标签3

cover

封面图片 URL，支持外部链接。显示位置：

• 博客首页文章列表中，标题下方
• 全部文章页面的卡片中
• 文章详情页，标题栏与正文之间

cover: https://img.iflux.art/arch-wsl2-cover.png

draft

草稿标记，设为 true 时文章默认不会出现在列表页中：

draft: true

getAllPosts() 默认过滤草稿。如需在预览环境中查看草稿，可使用 getAllPosts({ includeDrafts: true })。

完整示例

---
title: WSL2 安装 Arch Linux 完整指南
description: 在 WSL2 中安装 Arch Linux 的完整步骤摘要，适合搜索引擎收录。
excerpt: 从零开始在 WSL2 上部署 Arch Linux，包括系统初始化、镜像源配置和开发环境搭建。
category: 开发
tags: [Arch Linux, WSL2

三、Docs 站点

文件组织

Docs 按目录组织，每个目录下可以放置 _meta.json 文件来控制侧边栏的排序和显示名称：

src/content/docs/ ├── _meta.json ├── index.mdx ├── getting-started/ │ ├── _meta.json │ ├── index.mdx │ ├── introduction.mdx │ └── installation.mdx ├── grammar/ │ ├── _meta.json │ ├── index.mdx │ ├── general/ │ │ ├── _meta.json │ │ └── markdown.mdx │ └── shell/ │ ├── _meta.json │ └── bash.mdx └── ...

_meta.json 机制

_meta.json 是 Docs 站点独有的侧边栏配置文件，每个目录下都可以放置一个。

格式

每个 _meta.json 是一个 JSON 对象，键为文件名或目录名（不含扩展名），值为显示名称（字符串）或配置对象：

{
  "getting-started": "快速开始",
  "grammar": "语法基础",
  "system": "操作系统"
}

对象格式支持额外配置：

{
  "index": "智能体",
  "claude-code": "Claude Code",
  "openclaw": {
    "title": "OpenClaw",
    "collapsed": true
  }
}

多级嵌套

子目录可以有自己的 _meta.json，控制子项的排序和名称：

// grammar/_meta.json
{
  "index": "语法基础",
  "general": "通用语法",
  "shell": "Shell 与命令行",
  "tools": {
    "title": "开发工具",

标题优先级

文档标题的来源优先级（从高到低）：

1. Frontmatter 中的 title 字段 — 最高优先
2. _meta.json 中配置的名称
3. 文件名（去掉扩展名）作为降级

侧边栏折叠

在 _meta.json 中将某个分组设为 collapsed: true 后，该分组在侧边栏中默认折叠，点击标题可展开/收起：

{
  "index": "语法基础",
  "general": "通用语法",
  "shell": {
    "title": "Shell 与命令行",
    "collapsed": true
  }
}

未设置 collapsed 的分组默认展开。

Frontmatter 字段

Docs 的 Frontmatter 通过 DocsFrontmatterSchema 进行 Zod 校验：

Docs 不需要 date、tags、category 等字段，因为分类由目录结构决定，排序由 _meta.json 控制。

完整示例

---
title: WSL2 安装与通用配置指南
description: Windows 上的 WSL2 从零安装到开发环境搭建的完整配置流程。
---

四、两者对比

五、写作流程

Blog 新建文章

1. 在 apps/blog/src/content/posts/ 下创建 .mdx 文件
2. 文件名用英文短横线格式，如 my-post.mdx
3. 编写 Frontmatter：

---
title: 文章标题
description: SEO 描述，150 字符以内
excerpt: 文章摘要，显示在列表卡片中
category: 分类名
tags: [标签1, 标签2]
date: 

1. 正文使用 Markdown + MDX 编写

Docs 新建文档

1. 在 apps/docs/src/content/docs/ 对应分类目录下创建 .mdx 文件
2. 在该目录的 _meta.json 中添加条目并设置显示名称
3. 编写 Frontmatter（只需 title 和 description）：

---
title: 文档标题
description: 文档的 SEO 描述
---

1. 正文使用 Markdown + MDX 编写

六、Zod 校验规则

Blog 的 Frontmatter 通过 @iflux/utils 提供的 parsePostFrontmatter 函数进行校验，底层使用 Zod：

const PostFrontmatterSchema = z.object({
  title: z.string().optional(),
  date: z.union([z.string(), z.date()]).optional

Docs 的 Frontmatter 通过 parseDocsFrontmatter 函数进行校验：

const DocsFrontmatterSchema = z.object({
  title: z.string().optional(),
  description: z.string().optional(),
  cover: z.string().optional(),

校验失败时不会导致构建中断，而是降级使用默认值（标题取文件名，日期取空字符串），并在日志中输出警告。这个设计保证了即使 Frontmatter 写得不太规范，文章依然可以正常渲染。