基本概念

一个专门的技术术语，指放在文档(通常是 Markdown 文件)最开头的一段元数据(metadata),用来描述这个文档本身的属性——比如标题、日期、作者、标签等,但不属于正文内容。

为什么叫 "Front Matter"？

• front = 前面的
• matter 名词，意思是"内容/材料"(不是动词)

Front Matter 字面意思就是 "放在前面的内容/材料"，引申为 文档开头的元数据块。

这个词最早来源于印刷/出版行业，指一本书正文之前的部分(比如书名页、目录、序言等)，后来被借用到技术文档领域，特别是 Markdown/MDX 生态。

常见翻译:

• 前置元数据
• 元数据头
• 文档头信息
• 业内很多时候也直接不翻，说Front Matter或frontmatter

Front Matter 已经是 Markdown/MDX 生态中事实上的标准模式之一。很多内容系统会有：

---
title: Hello World
date: 2026-08-11
tags:
  - nextjs
  - mdx
---
 
正文……

这里面：

• Front Matter：指整个头部元数据区域；
• YAML：指里面的数据语法；
• ---：是该 Front Matter 格式使用的 delimiter（分隔符）；

大量 Markdown/MDX 生态相关工具通过该方式区分元数据和正文内容，该方式同时可以让文档文件脱离具体框架：

Markdown/MDX
       │
       ├── Front Matter → metadata
       │
       └── Body → content

定义与约定

• Front Matter 是在 Markdown、MDX 等内容文件头部声明结构化元数据的一种约定。
• YAML 是 Front Matter 最常见的数据格式，因此经常会看到 YAML Front Matter 这个说法。
• 除 YAML 外，Front Matter 也可以采用 TOML、JSON 等格式，具体取决于所使用的工具或框架。
• 在 Markdown / MDX 生态中，如果没有特别说明，Front Matter 通常指 YAML Front Matter，但二者严格来说并不完全等同。

Front Matter
└── 一种“文档头部元数据”约定
    ├── YAML Front Matter
    ├── TOML Front Matter
    └── JSON Front Matter

YAML Front Matter

• YAML Front Matter 通常位于文件顶部，并使用 --- 作为起止分隔符。

---
title: 我的文章标题
date: 2026-08-11
tags: [AI, 编程]
---
 
这里才是正文内容...

支持的数据类型

不要把 Front Matter 想象成只能放字符串，它的数据类型非常灵活，对于内容元数据而言，它的表达能力通常完全够了。常见的数据类型有：

# 字符串
title: Next.js Docs
 
# 数字
order: 10
 
# 布尔
published: true
 
# null
deprecated: null
 
# 数组
tags:
  - nextjs
  - react
  - routing
 
# 对象
author:
  name: Ocean
  role: Developer
 
# 对象数组
links:
  - title: Getting Started
    href: /getting-started
  - title: Routing
    href: /routing

和 JavaScript 对象的区别

related:
  title: Next Steps
  description: Create your first application
  links:
    - app/getting-started

转换为 JavaScript，大致如下：

{
  related: {
    title: "Next Steps",
    description: "Create your first application",
    links: [
      "app/getting-started"
    ]
  }
}

有些系统喜欢定义一个 JavaScript 对象来充当 Front Matter，大致如下：

export const metadata = {
  title: 'Dynamic Routes',
  description: 'Learn how Dynamic Routes work.',
  order: 3,
}
 
# Dynamic Routes
 
When you don't know the exact segment names...

这种方式也是可以的，但是性质发生了一点变化：

Front Matter 是数据；export const metadata 是 JavaScript/TypeScript 模块代码。

这一点在技术实现上有很大的区别。特别是大型文档系统。

假设 Next.js 仓库里有：

docs/
├── 01-app/
│   ├── 01-getting-started.mdx
│   ├── 02-routing.mdx
│   └── 03-rendering.mdx

某个构建脚本想扫描所有文档：

扫描 docs
    ↓
读取 Front Matter
    ↓
得到 title / description / links / order
    ↓
生成目录、导航、搜索索引

它只需要：

读取文本
→ 找到 ---
→ YAML parse
→ 得到普通对象

根本不需要编译 MDX。

如果元数据是：

export const metadata = {
  title: getTitle(),
  order: config.order + 1,
}

因为这已经不再是纯数据，而是可执行代码。工具可能需要解析 JS AST、编译/加载模块，甚至面对 import 和运行环境问题。

所以 Front Matter 有一个非常重要的工程属性：

Static Data / Declarative Data——静态、声明式、容易被任何工具读取。

如果它是“关于这篇内容的数据”，优先 Front Matter。

如果它需要执行、计算、import 或依赖程序环境，才考虑 JS/TS export。

Front Matter 不是因为 YAML 比 JavaScript 对象强，而恰恰是因为它更弱、更静态、更声明式，所以特别适合作为 Markdown/MDX 的内容元数据。