YAML front-matter 解析——给 Markdown 文件加元数据，预览模式可配置显示

什么是 YAML front-matter

YAML front-matter 是很多静态站点生成器（Jekyll / Hugo / Hexo / MkDocs 等）和知识管理工具（Obsidian）使用的标准——在 Markdown 文件开头，用两条 --- 包裹一段 YAML 格式的元数据。

---
title: 给 Markdown 文件加元数据
date: 2026-10-14
tags: [markdown, tutorial]
author: 张三
---

## 正文从这里开始

这是正文内容...

Markor 对 YAML front-matter 的处理

v2.9 新增了解析能力：

• ✅ 编辑器模式：front-matter 块用特殊样式高亮（灰色边框或特殊背景色），和正文区分
• ✅ 预览模式：front-matter 可以被配置为 显示为表格 或 完全隐藏
• ✅ 可配置显示哪些字段（Settings → Format → Markdown → YAML front-matter → 勾选要显示的 key）

显示规则配置

开启显示

1. Settings → Format → Markdown → YAML front-matter
2. 勾选 Display in view mode
3. 下面会列出所有可能显示的 key——你可以勾选具体要显示哪些，或全选显示全部

显示效果

勾选后，预览模式里 front-matter 会渲染成一个独立的 元数据表格，放在正文之前：

┌──────────┬───────────────────┐
│ title    │ 给 Markdown 文件加元数据 │
│ date     │ 2026-10-14         │
│ tags     │ markdown, tutorial │
│ author   │ 张三               │
└──────────┴───────────────────┘

关闭显示

如果完全不想在预览里看到 front-matter：

• Settings → Format → Markdown → YAML front-matter → 不勾选 Display in view mode

常见用途

和其他工具的兼容性

因为 Markor 写的是 标准 YAML front-matter，跨平台零问题：

• Jekyll / Hugo / Hexo → 直接用，不修改
• Obsidian → 支持 front-matter，Obsidian Properties 可以直接读
• Pandoc → pandoc input.md 时 front-matter 会被当作 pandoc 的 YAML metadata block 处理

注意事项

⚠️ YAML front-matter 必须写在文件最开头——第一条就是 ---，中间不能有空行，后面紧跟着第二条 ---。任何偏差（前面空行、--- 写法不同）都会导致 Markor 识别失败。

❌ 错误（前面有空行）：

---
title: test
---

✅ 正确：
---
title: test
---

Markdown front-matter 和 KaTeX 的关系

如果你的 Markdown 文件里 同时 有 front-matter 和 KaTeX 公式：

1. front-matter 块 永远在最开头
2. 正文从第二条 --- 之后开始
3. KaTeX 公式只写在正文里，不要写在 front-matter 的 YAML 字段值里（除非你用引号包起来）

Markor 能正确识别这种混合结构，不会把 front-matter 里的字段值当成 KaTeX 公式渲染。