Markdown 文件顶部由 --- 包裹的那一块，是描述这个文件本身的元数据，不属于正文。

---
title: 我的笔记
tags:
  - type/note
  - domain/cs-ai
date: 2026-08-07
---

正文从这里开始。

名字的来源

这个术语是两部分拼起来的。

front matter 借自出版业。front 是前面，matter 在出版术语里指书稿内容。一本书正文之前的那几页（封面、版权页、献词、目录）就叫 front matter：它们不是正文，而是描述这本书本身——谁写的、何时印的、分几章。

Markdown 顶部这块头干的是同一件事：不是正文，而是描述这个文件（标题、标签、日期、别名）。所以叫「前置内容」。

YAML 是写它的格式。YAML (YAML Ain't Markup Language) 是一种以缩进表达层级的数据序列化格式，key: value 加缩进列表就是它的语法。

合起来，YAML frontmatter = 用 YAML 语法写在文件头部的前置元数据。

这个约定来自 Jekyll

这套写法不是笔记软件发明的。2008 年前后，静态站点生成器 Jekyll（GitHub Pages 的默认引擎）引入了这个约定：在 Markdown 文件顶部用 --- 包一段 YAML 写元数据，官方文档称之为 YAML Front Matter。Jekyll 用它决定文章标题、发布日期、用哪个模板渲染。

后来的生态基本全部沿用：

  • Hugo — Go 写的静态站点生成器，以构建速度快著称，是 Jekyll 最主要的替代品
  • Obsidian — 用 frontmatter 里的 tags / aliases 驱动标签系统和双链
  • VitePress / Docusaurus / Astro — 现代文档站，用它控制页面标题、侧边栏位置、是否草稿

所以今天你在任何笔记工具或博客框架里看到这块头，都是同一个传统的延续。

位置是硬约定

解析器只认文件最开头的 --- 块。第一行必须是 ---，中间不能有空行或其他内容。

写在文件中间的 --- 只是普通的 Markdown 水平分隔线，不会被当作元数据。这也解释了它为什么必须在顶部：它是「文件级」的信息，解析器读第一行就要拿到它，才能决定后面怎么处理。

分隔符的语义

--- 本身就是 YAML 标准里的文档起始标记 (document start marker)。YAML 允许一个文件里放多个文档，用 --- 分隔。frontmatter 正是借用了这个机制：把元数据当作第一个 YAML 文档，--- 天然地把它和后面的正文隔开。

不是只能用 YAML

同一个「文件头元数据」的位置，格式可以替换：

格式分隔符常见于
YAML---Jekyll、Obsidian、Hugo（默认）
TOML+++Hugo
JSON{ }Hugo、部分工具链

YAML 是事实标准，因为最易读，且是 Jekyll 留下的老传统。

常见坑

  • 缩进只能用空格，不能用 Tab。YAML 明确禁止 Tab 缩进，用了会解析失败。
  • 冒号后必须有空格。tags:value 不合法，要写 tags: value。
  • 含特殊字符的值要加引号。值里出现 :、#、[ 等符号时，用引号包住：title: "第 3 章: 开始"。
  • YAML 会自作聪明转换类型。yes / no / on / off 会被解析成布尔值，1.0 会变成数字。想要字符串就加引号。

关联

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/General