Markdown Front Matter：YAML 頭資訊完全指南

你打開一個 Markdown 檔案，發現頂部有一段被 --- 包裹的內容——那就是 front matter。它不顯示在頁面上，卻在背後默默控制著文章的標題、日期、標籤、模板這些重要資訊。

如果你用 Jekyll、Hugo 架設過部落格，或者在 Obsidian 裡管理筆記，front matter 幾乎繞不開。這篇文章會把 YAML 頭資訊的語法、寫法、各個工具的差異，以及我自己踩過的坑，一次性講清楚。對 Markdown 語法有基本了解就能跟得上。

什麼是 Front Matter

Front matter 就是 Markdown 檔案最開頭的一段元資料（metadata），用三個短橫線 --- 作為開始和結束標記，中間寫 YAML 格式的鍵值對。它告訴處理這個檔案的工具：「嘿，這篇文章的標題是這個，日期是那個，分類是這些。」

一個最簡單的例子：

---
title: 我的第一篇文章
date: 2026-05-13
---

正文內容從這裡開始...

有幾個硬性規則：front matter 必須是檔案的第一行內容（前面不能有空行），兩個 --- 之間的內容必須是合法的 YAML，而且結尾的 --- 不能省略。

有一點容易混淆——--- 在 Markdown 正文裡表示水平分隔線，但出現在檔案最頂部時，所有主流解析器都把它識別為 front matter 的起始標記，不會當作分隔線處理。

YAML 語法速查

Front matter 裡的內容遵循 YAML 語法規範。如果你之前沒接觸過 YAML，這裡過一遍核心寫法就夠了。

基本鍵值對

title: 我的第一篇文章
author: 張三
draft: false
views: 1024

冒號後面加一個空格，值就直接寫在後面。布林值用 true / false，數字直接寫。

一個很容易踩的坑：如果你的值裡包含冒號 : 或者井號 #，必須加引號，否則解析器會報錯。比如：

title: "入門指南：從零開始"
description: "技巧 #1：保持簡潔"

不加引號的話，: 後面的內容會被當作新的鍵值對，# 後面的內容會被當作註解忽略掉。

列表

兩種寫法都行，看你喜歡哪種：

行內寫法：

tags: [markdown, yaml, 教程]

多行寫法：

tags:
  - markdown
  - yaml
  - 教程

巢狀物件

seo:
  title: "SEO 標題"
  description: "頁面描述"
  image: "/images/cover.png"

巢狀層級用兩個空格縮排。說實話，我以前習慣用 Tab 鍵縮排，結果 Jekyll 建置直接報錯——YAML 規範只認空格，Tab 會導致解析失敗。這是新手最常見的錯誤之一。

日期格式

推薦用 ISO 8601 格式：

date: 2026-05-13
lastmod: 2026-05-13T14:30:00+08:00

有些工具只要日期部分就行，有些要求完整的時間戳。具體看你所用工具的文件。

常用欄位一覽

不同工具支援的欄位不完全一樣，但下面這些是「通用款」，大部分平台都認：

這些欄位名稱是約定俗成的，不是 YAML 標準定義的。換個說法，你可以寫 banana: true，但不會有任何工具認識這個欄位——它只會被靜默忽略。

不同工具的差異對比

這是我覺得寫 front matter 時最容易讓人困惑的部分：同一個欄位，在不同工具裡行為不一樣。我對比了幾個主流工具：

拿 draft 欄位舉個例子：在 Hugo 裡，draft: true 的文章在生產建置時會被自動跳過，非常方便；但在 Jekyll 裡，預設情況下草稿文章也會被發佈出去，除非你手動加 --drafts 參數或者在 _drafts 目錄下管理。

這些差異是我在同時維護一個 Jekyll 部落格和一個 Hugo 文件站時總結出來的，踩了不少坑才搞清楚。

一個完整的 Front Matter 範例

下面是一個接近實際專案會用到的設定：

---
title: "Markdown Front Matter 完全指南"
date: 2026-05-13T10:00:00+08:00
author: "張三"
tags:
  - markdown
  - yaml
  - 教程
categories:
  - 技術文件
description: "從 YAML 語法到工具差異，一篇搞懂 Markdown Front Matter 的方方面面。"
draft: false
slug: markdown-front-matter-guide
seo:
  title: "Markdown Front Matter & YAML 頭資訊"
  description: "什麼是 front matter，怎麼寫，各有什麼區別。"
  image: "/images/frontmatter-cover.png"
---

## 正文從這裡開始

你的文章內容...

常見問題排查

寫 front matter 時遇到問題，大概率是以下幾種情況：

YAML 解析錯誤

症狀：工具報錯說 front matter 無效，或者欄位值不是你期望的。

排查思路：

1. 縮排是否用了空格——Tab 會導致解析失敗，這是排名第一的原因
2. 冒號後面有沒有空格——title:我的文章（錯誤）vs title: 我的文章（正確）
3. 特殊字元是否加了引號——包含 : # [] 的值需要用引號包裹
4. 列表縮排是否對齊——多行列表的 - 前面縮排要一致

Front Matter 不生效

症狀：明明寫了 front matter，但工具好像沒識別到。

常見原因：

• front matter 前面有空行或 BOM 字元（檔案編碼問題）
• 使用了 ... 而不是 --- 作為結束標記（部分工具不支援）
• 檔案副檔名不對（比如 Jekyll 要求 .md 或 .html）

值被錯誤解析

version: 1.0

你以為 version 是字串 "1.0"，但 YAML 解析器會把它當作浮點數 1.0。解決方法：加引號。

version: "1.0"

類似的情況還有 true/false/yes/no/on/off——YAML 會把這些全部解析為布林值。如果你的值恰好是這些詞（比如標籤 tags: [on, off]），記得加引號。

用程式碼解析 Front Matter

有時候你需要批次處理 Markdown 檔案，提取 front matter 裡的元資料。JavaScript 生態裡最常用的函式庫是 gray-matter：

const matter = require('gray-matter');

const file = matter.read('./article.md');
console.log(file.data);    // { title: '...', date: '...', tags: [...] }
console.log(file.content); // '---' 下面的正文內容

Python 使用者可以用 python-frontmatter：

import frontmatter

with open('article.md') as f:
    post = frontmatter.load(f)

print(post['title'])   # 文章標題
print(post.metadata)   # 完整的 front matter 字典
print(post.content)    # 正文內容

兩個函式庫的思路一樣：把 Markdown 檔案拆成 data（元資料）和 content（正文）兩部分，分別處理。

參考來源

• Jekyll 官方文件 — Front Matter
• Hugo 官方文件 — Front Matter
• VitePress 官方文件 — Frontmatter
• GitHub Docs — Using YAML Frontmatter
• YAML 1.2 規範