Markdown frontmatter 是什么？YAML 转 JSON 完整指南

Markdown 文件开头用 --- 包起来的 YAML 块，就是 frontmatter。往无头 CMS 灌数据、用构建脚本只提取元信息、在不同静态站点生成器之间迁移、给 LLM 喂结构化上下文——这些场景都需要把 frontmatter 从 YAML 转成 JSON。

最快的做法：打开 Markdown 文件，把两个 --- 之间的 YAML 内容复制出来，粘贴到 YAML JSON 转换工具。FormatArc 的所有转换都在浏览器内完成，内部 Wiki 的 frontmatter 或未发布文章的数据都不会传出去。

这篇文章讲完整的转换流程：frontmatter 的结构、各 SSG 支持的格式、提取步骤、5 种容易出错的类型，以及反向操作（JSON 转回 YAML frontmatter）。

结论：frontmatter 是「分隔符 + YAML 正文」，转换时只传正文

一篇典型的 Markdown frontmatter 长这样：

---
title: "第一篇文章"
date: 2026-06-22
tags: ["intro", "demo"]
draft: false
---

正文从这里开始。

上下两条 --- 在 YAML 规范里叫文档分隔符（document separator），但把 frontmatter 交给解析器或在线转换工具时，最稳妥的做法是只取中间那 4 行 YAML 正文。

把上面例子里 title 到 draft 之间的内容粘贴到 YAML JSON 转换工具，立刻得到：

{
  "title": "第一篇文章",
  "date": "2026-06-22",
  "tags": ["intro", "demo"],
  "draft": false
}

注意各字段的类型：title 和 date 是字符串，tags 是数组，draft 是布尔值。YAML 的隐式类型推断做对了，JSON 输出才可靠。

为什么要转 frontmatter：4 种常见场景

frontmatter 转 JSON 的需求集中在以下 4 类。你属于哪一类，决定了提取范围和注意事项。

1. 无头 CMS / API 对接

Contentful、Strapi、Sanity、飞书多维表格这类无头 CMS 用结构化 JSON 管理文章元数据。团队之前用 Markdown 文件维护博客，现在要迁到 CMS，标准流程就是：frontmatter 转 JSON，作为 REST 或 GraphQL 请求体的一部分。

2. 构建脚本只取元数据

生成"文章索引 JSON""按标签统计""按日期归档"这类构建产物时，不需要解析整篇正文，把 frontmatter 转成 JSON 就够了。Node.js 环境用 gray-matter，Python 环境用 python-frontmatter，都是社区标准做法。

3. SSG 之间迁移

从 Jekyll 换到 Astro，或者从 Hugo 换到 Next.js，需要逐篇检查 frontmatter 的字段名和数据结构。Hugo 的 params.foo 命名空间和 Astro Content Collections 的 schema 不兼容，中间用 JSON 做一次归一化映射是最省事的。

如果源头不是 SSG 而是 WordPress，那 frontmatter 本身不存在，需要从导出数据里拼装 title、date、slug，再组装出 frontmatter 写回文件。

导出 WordPress 文章到 Markdown 的具体做法，见 WordPress 导出 Markdown 的三种方法.

4. LLM / RAG 上下文结构化

把 Markdown 文档喂给 ChatGPT、Claude 或向量数据库的 RAG 管道时，把元数据以 JSON 形式和正文分开传，检索精度和摘要质量都会好。因为标签、分类、日期变成了机器可读的结构化字段，而不是埋在 YAML 前言里的文本。

frontmatter 的 3 种格式：YAML、TOML、JSON

frontmatter 不一定都是 YAML。不同 SSG 接受的格式不同，这是跨工具摩擦的主要来源。

YAML frontmatter（最通用）

---
title: "你好，世界"
date: 2026-06-22
---

用 3 个连字符 --- 包裹。Jekyll、Hugo、Astro、Eleventy、Gatsby、Docusaurus，几乎所有主流 SSG 都默认支持。

YAML 的基本写法和注释规则，可以参考 YAML 是什么.

TOML frontmatter（Hugo / Zola）

+++
title = "你好，世界"
date = 2026-06-22
+++

用 3 个加号 +++ 包裹。Rust 写的 Zola 要求必须用 TOML，Hugo 则 YAML、TOML、JSON 三种都认。

JSON frontmatter（Hugo / Eleventy）

{
  "title": "你好，世界",
  "date": "2026-06-22"
}

花括号 { ... } 本身就充当分隔符。Hugo 和 Eleventy 原生解析，但 Astro 和 Jekyll 不识别 JSON frontmatter。

各 SSG 的 frontmatter 格式兼容矩阵

主要静态站点生成器默认支持哪些 frontmatter 格式，对照如下：

从这张表能直接读出两个高频转换场景：

• 往 Astro、Jekyll、Gatsby、Docusaurus 灌数据时，JSON frontmatter 必须先转成 YAML。
• 往 Zola 迁移时，所有 frontmatter 要从 YAML 批量转成 TOML。

反过来，Hugo 和 Eleventy 兼容性最好，现有 YAML 或 JSON 数据不用改就能直接用。

从 Markdown 文件里只提取 frontmatter 正文

粘贴到转换工具之前，需要把 YAML 正文从整篇文档里切出来。步骤很简单：

1. 确认第 1 行是 ---，前面不能有空行（有前导空行时解析器不会识别为 frontmatter）
2. 从第 2 行往下找下一行独立的 ---
3. 两个 --- 之间的内容（不含 --- 本身）就是 YAML 正文

把切出来的 YAML 粘贴到 YAML JSON 转换工具，浏览器内立刻出结果。FormatArc 不经过任何服务器，未发布文章、内部配置、CMS 里含密钥的 payload 都可以安全处理。

几百个文件的批量处理用 CLI 脚本自动跑，单个文件的配置校验或 CMS 提交前肉眼确认用浏览器工具更省事。

常见的解析报错及修复

• parse error: bad indentation：缩进里混了 Tab 和空格。统一用 2 个空格就能解决。
• mapping values are not allowed here：值里包含冒号但没加引号。改成 title: "10:00 会议记录" 这样用双引号包起来。
• could not find expected ':'：列表项 - 后面或键 : 后面漏了空格。

YAML 的缩进、引号等格式规范更完整的说明，见 YAML 语法指南.

反向操作：JSON 转回 YAML frontmatter

从 CMS 或数据库拿到的 JSON 元数据要写回 Markdown 文件时，需要反向转换。把 JSON 对象粘贴到 JSON YAML 转换工具，生成 YAML 后上下各加一条 --- 就是合法的 frontmatter：

---
{ 这里放 YAML 转换结果 }
---

正文内容……

往 Astro、Jekyll、Gatsby 这类不支持 JSON frontmatter 的框架里导 CMS 数据时，这一步是必须的。

YAML 转 JSON 时容易出问题的 5 种类型

YAML 和 JSON 的类型系统有重叠但不完全一致。以下 5 类在 frontmatter 转换中最容易翻车。

两者在语法、注释和解析行为上的差异，可以对照 YAML 和 JSON 的区别.

1. 日期类型（Date）

YAML 1.1 解析器会把 2026-06-22 解析成日期对象，但 JSON 没有 Date 类型，序列化后变成字符串。确认输出是带引号的 "2026-06-22" 而不是数字或对象。带时区的 2026-06-22T10:00:00+08:00 保持为 ISO 8601 字符串不变。

2. 多行字符串（Multiline）

YAML 的 |（保留换行）和 >（换行折叠为空格）两种块标量，转成 JSON 后变成带 \n 转义符的单行字符串。

description: |
  第一行内容。
  第二行内容。

转换后：

{
  "description": "第一行内容。\n第二行内容。\n"
}

确认换行符位置和数量符合预期。

3. 锚点与别名（& / *）

YAML 的锚点（&id）和别名（*id）用来复用同一个对象或值。JSON 没有引用概念，别名引用的值会被展开成独立副本。为了节省内存写的共享结构，在 JSON 里会变成文件体积膨胀。

4. 自定义语言标签（!Ruby/Symbol 等）

Jekyll 的 Ruby 符号或 PyYAML 的 !!python/object: 这类语言专属标签无法表达为标准 JSON。大多数转换工具会报错，或者忽略标签只保留纯值。

5. 布尔误判与"挪威问题"

YAML 1.1 规范里，true/false 之外的 yes、no、on、off、y、n 也会被自动识别为布尔值。写 country: NO（挪威）会被解析成 country: false。这就是有名的"挪威问题"。

需要保持字符串类型的值，写 YAML 时务必加引号："NO"。

工具对比：浏览器转换 vs CLI / npm 包

frontmatter 转换工具有好几款，各有所长，按场景选：

几百篇文档周期性构建的 CI/CD 环境用 CLI 库；临时校验一次、或处理不允许外传的内部文档用浏览器工具。两者互补，不冲突。

如果想了解 yq、Python 等工具转换 YAML 时的常见陷阱，见 YAML 转 JSON 指南.

实战模式

Contentful / Strapi 迁移

CMS 的 Content Model 字段名和 frontmatter 的键名对不上时，转成 JSON 后写个映射脚本，或者手动改键名再提交 API。一次性迁移手动改就行，反复同步就在 gray-matter 输出上套一个映射函数。

Notion 导出的 Markdown 处理

Notion 导出的 Markdown 默认不带 YAML frontmatter。页面属性可以单独导出为 JSON，和正文合并后组装成 frontmatter，再走后续 CMS 导入流程。比从页面标题反向猜元数据可靠得多。

CI 管道里做 JSON Schema 校验

博客或技术文档仓库的 PR 提上来时，把每篇文件的 frontmatter 转成 JSON，用 ajv 之类的库跑 JSON Schema 校验：必填字段（title、date、tags）是否存在、日期格式是否合规、tags 是否为空数组。在 PR 阶段就拦住 schema 漂移，比上线后排查便宜得多。

容易踩的坑

• 正文水平线（---）和 frontmatter 分隔符冲突：Markdown 水平线也写 ---，正文里如果有一条 ---，部分解析器会误认为 frontmatter 结束。正文水平线用 *** 或 ___ 代替。
• 全角冒号（：）输入错误：用中文输入法时 : 容易打成 ：。YAML 解析器不认全角冒号作为键值分隔符，直接报语法错误。
• 前导零的标识符（邮编、工号等）：code: 01234 会被 YAML 解析器当八进制或整数处理，前导零丢失。要保留字符串就用 "01234"。
• 缩进里混入 Tab：YAML 规定缩进只能用空格。一个 Tab 字符就会触发 found character that cannot start any token 报错。编辑器里把 Markdown 文件的 Tab 替换设为 2 个空格，可以一次根治。

常见问题

frontmatter 能直接写 JSON 吗？

可以，前提是你的 SSG 支持。Hugo 和 Eleventy 默认接受 { ... } 形式的 JSON frontmatter。但 Astro、Jekyll、Gatsby、Docusaurus 不识别，需要通用兼容性的话还是用 YAML。

Obsidian 的 frontmatter 也能转 JSON 吗？

能。Obsidian 的属性和 frontmatter 遵循标准 YAML 格式，把笔记顶部的 --- 块原样复制出来转就行，不需要额外处理。

把 --- 分隔符也粘贴进转换工具会报错吗？

取决于工具。YAML 规范里 --- 是合法的文档起始标记，但部分转换解析器处理不了顶层分隔符，会返回空对象。保险起见只粘贴分隔符内部的 YAML 正文。

用 FormatArc 转换时数据会传出去吗？

不会。FormatArc 的所有转换逻辑以 JavaScript 在浏览器里运行，你粘贴的内容和转换结果都不经过任何服务器。内部配置文件和未发布草稿都可以安全使用。

总结：frontmatter 转换 4 步走

Markdown frontmatter 的 YAML 转 JSON 流程：

1. 从 Markdown 文件里复制两个 --- 之间的 YAML 正文（不含 --- 本身）
2. 粘贴到 YAML JSON 转换工具，浏览器内即时转换
3. 检查输出 JSON 里日期、多行字符串、布尔值的类型是否正确
4. 把 JSON 交给无头 CMS、构建脚本、schema 校验器或 LLM 管道

需要反向操作时，用 JSON YAML 转换工具 把 JSON 转回 YAML，上下加 --- 就是 frontmatter。SSG 迁移时先对照上面的兼容矩阵确认目标格式，再批量转换。