Frontmatter（元数据）

Frontmatter 是写在 Markdown 文件最开头的一段 YAML 元数据，用 --- 包裹。它不影响正文显示，却能为笔记添加标题、标签、日期、发布状态等结构化信息。

在即时渲染模式下，Frontmatter 会渲染为带 YAML 语法高亮的可编辑块（顶部有 METADATA 标签条），可以直接在块内增删改键值；源码模式下它就是普通的 YAML 文本。

基本语法

在文件第一行开始，用 --- 包裹 YAML 内容：

---
title: 我的笔记标题
tags: [标签1, 标签2]
date: 2024-01-01
---

之后才是正文内容。

支持的属性

属性 类型 说明
title string 文档标题（覆盖文件名显示）
tags string[] 标签列表，如 [读书, 技术]；会并入标签索引
date string 创建日期，建议 YYYY-MM-DD
publish string 发布状态；public 表示允许在「仅公开笔记」模式下发布
author string 作者
description string 文档描述（用于发布站点的 SEO）
tags 里声明的标签与正文中 #标签 写法效果一致，都会进入标签索引，可在侧栏「标签」页签中查看与筛选。详见 03-知识管理/06-标签。

在编辑器中编辑

即时渲染模式

Frontmatter 显示为编辑器顶部的一个高亮块：

  • 顶部有 METADATA 标签条，便于与其他内容区分
  • 块内是纯 YAML 文本，带语法高亮（键、字符串、数字、布尔值分别着色）
  • 直接点击即可编辑，按行增删键值即可，无需切换到源码模式
该块是纯文本编辑区域，不提供「键值表单」式的字段控件；键名与 YAML 语法需自行书写。

源码模式

直接编辑文件开头的 --- 块即可。

发布控制

Frontmatter 中的 publish 属性决定笔记是否参与「仅公开笔记」发布模式：

---
title: 公开笔记
publish: public
---
  • 设为 publish: public → 在「仅公开笔记」模式下会被包含
  • 不写或写其他值 → 仅「完整发布」模式才会包含

发布模式差异详见 08-高级功能/01-发布网站。

编写规范

  • Frontmatter 必须位于文件最开头，之前不能有任何字符（包括空行）
  • 使用 --- 开始，再用 --- 结束
  • 遵循标准 YAML 语法：字符串可加引号，数组用 [ ]，支持数字与布尔值
  • 属性名区分大小写（建议全小写）
如果 YAML 语法有误（如少了结束的 ---、缩进错乱），Frontmatter 可能无法被正确解析，渲染块中会显示异常。

相关文档