Markdown front matter 写法与渲染

Q: 能在笔记开头用 --- 当分隔线吗？

用 ***，或者先写一个标题。在妙言里，以 --- 开头且后面还有另一行 --- 的笔记会被当成 front matter。

Markdown 写作2026年10月19日约 3 分钟

Front matter 是 Markdown 文件最顶部的一段元数据，用两行 --- 围起来，内容写成 YAML，这样静态站点生成器在渲染正文之前就能读到标题、日期和标签。它必须放在第一行，上面不能有任何东西，结尾要有独占一行的 ---，值里带冒号时要加引号。妙言 V4.5.0 会在预览和导出里隐藏这样的一段，前提是文件以 --- 开头并用另一行 --- 收尾，用 +++ 写的 TOML front matter 不会被识别。

写法

---
title: Markdown front matter
date: 2026-10-19
tags: [markdown, notes]
draft: false
---

正文从这里开始。

开头的 --- 必须是第一行。键值就是普通 YAML，列表可以像上面这样写在一行里，也可以逐行写 - item，值里有冒号时，比如 title: "Note: a test"，要加引号。Jekyll 的文档描述的也是同一种形状，也就是夹在三条短横线之间的合法 YAML，还说明只写一对空的短横线 Jekyll 同样会处理这个文件。它也提醒文件开头的 UTF-8 字节顺序标记会让它出问题，这是一个看起来没错的文件有时会失效的原因。

Pandoc 稍微宽松一些。它的手册说 YAML 元数据块以顶部的 --- 开始，以底部的 --- 或 ... 结束，开头那行后面不能紧跟空行，块也可以出现在文档后面，只要前面有一个空行。

各个生成器用哪些键

没有通用的键列表，每个生成器各定各的。

生成器	格式	文档里提到的键
Hugo	`---` 的 YAML、`+++` 的 TOML，或 JSON	`title`、`date`、`draft`、`weight`、`description`，以及 `tags` 这类分类法
Jekyll	三条短横线之间的 YAML	`layout`、`title`、`date`、`published`
Astro	YAML 或 TOML	标题、描述、标签这类自定义属性

Hugo 的文档说它通过分隔符判断格式，+++ 就是 TOML，并把 date、draft、title、weight 列为最常见的字段。Jekyll 的基础示例里是 layout 和 title，date 是文章变量，用 published: false 让文章不出现在生成的站点里。Astro 的 Markdown 指南说 frontmatter 用来定义标题、描述、标签这类自定义属性，再由你自己的组件读取。

TOML 的写法是这样：

+++
title = "Markdown front matter"
date = 2026-10-19
tags = ["markdown", "notes"]
+++

Hugo 按每个文件的分隔符选解析器，只认 --- 写法的工具会把 +++ 块当普通文字显示，妙言 V4.5.0 就是这样。

GitHub 怎么显示

GitHub 在 2013 年的博客里宣布（文章 2019 年更新过），会把文档顶部的 YAML 元数据渲染成横向的表格，读起来更方便，针对的正是 GitHub Pages 上 Jekyll 站点依赖的那段元数据。这对所有 GitHub 支持的文档格式都适用，不只是 Markdown。GitHub 的写作与格式文档里没有讲 front matter，能参考的就是这篇公告。

妙言 V4.5.0 怎么处理

规则写在 Business/Note.swift 的 Note.cleanMetaData 里。只有文本以 --- 加换行开头，或者 --- 加 Windows 换行开头，才会当作有 front matter。之后代码找下一行以 --- 开头的位置，这一行必须独占一行，才会把到它为止的内容全部去掉。结果用于预览、HTML 导出和 PDF 导出（二者建立在预览之上），也用于字数统计。编辑器里仍然显示原文，所以元数据照常编辑。

这个函数在 NoteFrontmatterTests 里有测试，固定了几种边界情况：

开头的块不管有没有 title: 键都会隐藏。
没有结尾分隔线的文件原样保留，全部显示。
结尾行写成 ---- 不算分隔线，整篇笔记连元数据一起显示。
只有 front matter 的文件，预览是空的。
笔记中间的三条短横线仍然是普通水平线。

妙言不会读这些键，那一段也不会按 YAML 解析，所以一篇笔记只要顶部恰好有两行 --- 夹着一些文字，预览里这些文字也会消失。同样没有 YAML 校验，能让 Jekyll 报错的笔误在妙言里看不出来。

幻灯片模式和 `---` 分隔符

幻灯片模式里 --- 同时是分页符。V4.5.0 在文本交给幻灯片渲染之前就去掉了 front matter，所以顶部的元数据块不会变成一页。要留意以 --- 当分隔符开头的幻灯片，如果后面还有一行 ---，两行之间的内容会被当成 front matter 而消失。幻灯片从标题开始写，元数据放进一个干净的块里。分隔符本身的用法见 Markdown 转幻灯片。

没有生效时

预览里显示出元数据。 第一个 --- 前面有空行或空格，结尾行是 ---- 或 ...，或者这个块用的是 +++。
正文上方出现标题。 块没有被识别为 front matter 时，紧跟着 --- 的一行文字在 CommonMark 里是 setext 标题，某个键就会变成一个大标题。
生成器忽略了文件。 检查文件开头有没有字节顺序标记，值里有没有没加引号的冒号。
文字不见了。 笔记顶部的两行 --- 在妙言里会隐藏它们之间的所有内容，即使那是想写的正文。

笔记还要发布到别处的话，可以看 Markdown 语法速查与 GFM 差异，了解各家渲染器在 CommonMark 之外加了什么。

常见问题

Front matter 算 Markdown 的一部分吗？

不算。CommonMark 没有定义它，这是静态站点生成器和部分编辑器的约定，它们会在渲染正文之前把它剥掉。

能在笔记开头用 `---` 当分隔线吗？

用 ***，或者先写一个标题。在妙言里，以 --- 开头且后面还有另一行 --- 的笔记会被当成 front matter。

GitHub 的 README 会显示 front matter 吗？

GitHub 2013 年的公告说，文档顶部的 YAML 元数据会显示成表格，它的写作与格式文档里没有提到 front matter。