---
title: YAML front matter
nav: YAML front matter
order: 3
description: 檔案最前面那段 --- 包起來的中介資料，在這裡會渲染成卡片，而不是被解析器吃掉。
updated: 2026-08-12
---

## 它是什麼

很多靜態網站產生器（Hugo、Jekyll、Astro）與筆記軟體（Obsidian）都約定：
檔案最前面可以放一段用 `---` 包起來的 YAML，用來記標題、日期、標籤這類中介資料。

```
---
title: 文章標題
date: 2026-08-12
tags: [markdown, editor]
draft: false
---

正文從這裡開始。
```

規則只有兩條，但都不能違反：

1. 開頭的 `---` 必須在**檔案的第一行**，前面連空行都不能有。
2. 用另一行 `---` 結束。

## 為什麼要特別處理

標準 Markdown 不認識 front matter。把上面那段餵給一般的解析器，你會得到：
第一行 `---` 變成分隔線，`title: 文章標題` 變成一段普通文字，
下一個 `---` 又變成分隔線 —— 也就是一坨壞掉的排版。

這個編輯器會先把 front matter 抽出來，渲染成一張標著 **YAML Front Matter** 的卡片，
剩下的正文才交給 Markdown 解析器。所以你在預覽裡看到的是：

> **YAML Front Matter**
> 一個框起來的區塊，裡面照原樣顯示你寫的欄位。

正文的第一個標題仍然是正文的第一個標題，不會被前面那幾行影響。

## 編輯器不會做的事

- **不驗證 YAML。** 縮排寫錯、冒號漏掉，卡片還是照樣顯示原文，不會報錯。要驗證請交給你的產生器。
- **不解析欄位。** `title` 不會變成預覽的標題，`draft: true` 也不會讓文件變灰。它只負責把這段中介資料完整保留、原樣顯示。
- **不會幫你補。** 新檔案不會自動塞 front matter。

這是刻意的：編輯器的職責是「不要弄壞你的檔案」，欄位怎麼解讀是產生器的事。

## 試一下

這一頁本身就是一個例子。用下面的連結把它下載成 `.md`，再用編輯器打開，
你會看到最上面那段 `title` 與 `order` 變成一張卡片。