FormatArc YAML to JSON 工具中將 Markdown frontmatter 轉為 JSON 的結果FormatArc YAML to JSON 工具中將 Markdown frontmatter 轉為 JSON 的結果
作者: FormatArc 編輯部發布日期: 2026-09-02更新日期: 2026-09-02

Markdown frontmatter 格式與語法：YAML 轉 JSON 的 5 個陷阱

Markdown 檔案開頭的 frontmatter（--- 包圍的 YAML 區塊）需要轉成 JSON 的場景，在日常開發中相當常見。無論是把文章搬進 headless CMS、build script 只抽取欄位做索引、在不同 SSG 之間遷移、還是喂給 LLM 做結構化的 RAG 情境，都會碰到這道轉換。

最快的方式是打開 Markdown 檔案，把開頭兩個 --- 之間的 YAML 本體複製出來，貼到 YAML to JSON。FormatArc 的轉換全部在瀏覽器內完成，所以非公開的文章或內部設定檔的內容不會外洩到任何伺服器。

這篇文章整理從 Markdown 檔案中安全擷取 frontmatter 並轉為 JSON 的步驟、各家 SSG 的支援格式對照表，以及轉換時最容易出錯的 5 種 YAML 型別。

結論：frontmatter 是「分隔線 + YAML 本體」，轉換時只傳本體

典型的 Markdown frontmatter 結構如下：

---
title: "我的第一篇貼文"
date: 2026-06-22
tags: ["intro", "demo"]
draft: false
---

正文的 Markdown 從這裡開始。

上下兩行的 --- 在 YAML 規範中是「文件分隔線」（document separator）。但如果你要把 frontmatter 丟給轉換工具或解析器，最穩妥的做法是只取中間的 YAML 本體，不要包含分隔線本身。

把上面例子中 title 到 draft 這 4 行貼到 YAML to JSON，會立刻得到：

{
  "title": "我的第一篇貼文",
  "date": "2026-06-22",
  "tags": ["intro", "demo"],
  "draft": false
}

注意各欄位的型別：title 和 date 是字串、tags 是陣列、draft 是布林值。YAML 的隱式型別推斷如果正確運作，JSON 輸出的對應才會準確。

FormatArc YAML to JSON 工具中將 frontmatter 轉為 JSON 的畫面FormatArc YAML to JSON 工具中將 frontmatter 轉為 JSON 的畫面

為什麼要把 frontmatter 轉成 JSON — 4 個常見場景

frontmatter 的轉換需求大致落在以下 4 種情境。你處於哪一種，決定了要抽取的範圍與要注意的重點。

1. Headless CMS 與 REST/GraphQL API 對接

Contentful、Strapi、Sanity、microCMS 這類 headless CMS 把文章的元資料當作結構化的 JSON 物件來管理。如果你之前用本地 Markdown 檔案維護部落格，現在要遷移進 CMS，標準流程就是把 frontmatter 轉成 JSON，再組進 API 的 POST payload。

2. Build script 只抽取元資料

要產生「全部文章列表 JSON」、「各 tag 文章數」、「按日期排列的索引」這類構件時，不需要解析整篇 Markdown 正文，只要把 frontmatter 轉成 JSON 就能快速統計。Node.js 環境常用 gray-matter，Python 環境則用 python-frontmatter。

3. 在不同 SSG 之間遷移

從 Jekyll 換到 Astro、或從 Hugo 換到 Next.js（Contentlayer/MDX）時，需要逐一审視 frontmatter 的 key 名稱與資料結構。例如 Hugo 的 params.foo 結構跟 Astro 的 Content Collections schema 並不直接相容，得先把 frontmatter 轉成 JSON 做中間映射。

如果來源是 WordPress 之類的 CMS 匯出的 Markdown，那原本就沒有 frontmatter，需要從匯出資料中拼出 title、date、slug 等欄位再組裝成 frontmatter。匯出後如何整理這些欄位，可參考WordPress 匯出 Markdown 的三條路徑比較。

4. LLM 與 RAG pipeline 的情境結構化

把 Markdown 文章餵給 ChatGPT、Claude 或向量資料庫背後的 RAG pipeline 時，如果先將元資料轉成 JSON 與正文分離送入，檢索準確度與回答品質都會比較穩定。因為 category、tags、date 等屬性變成機器可讀的結構化資料。

frontmatter 的 3 種格式：YAML、TOML、JSON

frontmatter 不一定永遠是 YAML。不同 SSG 接受的格式不同，轉換前釐清這一點可以減少很多混亂。

1. YAML frontmatter（最常見）

---
title: "Hello, world"
date: 2026-06-22
---

以 3 個減號 --- 開頭與結尾。Jekyll、Hugo、Astro、Eleventy、Gatsby、Docusaurus 等幾乎所有主流 SSG 都原生支援。

2. TOML frontmatter（Hugo / Zola 使用）

+++
title = "Hello, world"
date = 2026-06-22
+++

以 3 個加號 +++ 包圍。Rust 系靜態網站產生器 Zola 強制要求 TOML，Hugo 則 YAML、TOML、JSON 三者都接受。

3. JSON frontmatter（Hugo / Eleventy 支援）

{
  "title": "Hello, world",
  "date": "2026-06-22"
}

花括號 { ... } 本身就兼當分隔線。Hugo 和 Eleventy 會直接解析這種格式，但 Astro 和 Jekyll 預設不認識 JSON frontmatter。

各家 SSG 的 frontmatter 支援對照表

以下是主要靜態網站產生器與 Markdown 框架預設支援的 frontmatter 格式（2026 年中官方文件確認）：

SSG / 框架YAML (---)TOML (+++)JSON ({...})備註
Hugo支援支援支援.org 檔案的 Org Mode (#+) 也支援
Jekyll支援不支援不支援純 YAML，即使空文章也需要開頭 ---\n---
Astro支援支援不支援JSON frontmatter 需先轉成 YAML 或 TOML
Eleventy (11ty)支援需外掛支援TOML 預設不支援，需加自訂 parser
Next.js + MDX (@next/mdx)需外掛需外掛需外掛要加 remark-frontmatter 等 remark 外掛
Gatsby支援不支援不支援gatsby-transformer-remark 以 YAML 為前提
VuePress支援不支援不支援純 YAML
Zola不支援支援不支援TOML 必須，YAML 需先轉 TOML
Docusaurus支援不支援不支援純 YAML，底層用 gray-matter

從這張表可以看出兩個重點：

  • 如果目標是 Astro、Jekyll、Gatsby、Docusaurus：它們不接受 JSON frontmatter，必須先轉成 YAML。
  • 如果目標是 Zola：需要把全部文章的 YAML frontmatter 批量轉成 TOML。

Hugo 和 Eleventy 格式包容度最高，現有的 YAML 或 JSON 資料可以原樣使用。

從 Markdown 全文中擷取 frontmatter 本體

貼到轉換工具之前，需要先把 frontmatter 的 YAML 本體從 Markdown 全文中乾淨地分離出來：

  1. 確認第 1 行剛好是 ---（前面不能有空白行，否則 parser 不會認它為 frontmatter 開頭）
  2. 從第 2 行往下找，找到下一行單獨出現的 ---
  3. 兩行 --- 之間的內容（不含分隔線本身）就是 YAML 本體

把這段 YAML 貼到 YAML to JSON 就能即時轉換。FormatArc 全部在瀏覽器內執行，所以 API key、內部文件、未發布的貼文內容都不會傳到外部伺服器。

如果是幾百個檔案的批量處理，用 CLI script 自動化當然合理；但如果是「只想要確認一份檔案的設定值」或「CMS 註冊前想目視檢查 payload」，瀏覽器工具比較俐落。

常見的解析錯誤與解法

  • parse error: bad indentation：YAML 的縮排混用了 Tab 和 Space。統一成 2 個空格即可。
  • mapping values are not allowed here：值裡面含有冒號（:）但沒有加引號包住。例如 title: "10:00 會議紀錄" 需要雙引號。
  • could not find expected ':'：list 項目 - 後面或 key 的 : 後面漏了空格。

這些只列出了最常見的案例，YAML 的縮排規則與更多錯誤解法，可參考YAML 語法教學。

反向：把 JSON 轉回 YAML frontmatter

從 CMS 或資料庫拿到的 JSON 元資料，如果要寫回 Markdown 檔案的 frontmatter，就需要反向轉換。把 JSON 物件貼到 JSON to YAML 工具即可產生 YAML。

把產生的 YAML 放到 Markdown 檔案最上方，上下各補一列 --- 就完成了：

---
{ 這裡放 YAML 轉換結果 }
---

正文內容...

特別是你要把 JSON 格式的資料搬進 Astro、Jekyll、Gatsby 這些不支援 JSON frontmatter 的框架時，這一步是必要的。

YAML 轉 JSON 時容易出錯的 5 種型別

YAML 和 JSON 的型別系統雖然相近，但并不完全一致。兩者的完整差異（型別、註解、錨點等）可參考YAML JSON 比較。frontmatter 轉換時最容易出問題的 5 種型別如下：

1. 日期型別（Date）

YAML 1.1 parser 可能會把 2026-06-22 自動解析成日期物件，但 JSON 沒有獨立的 Date 型別，會序列化為字串。確認輸出是 "2026-06-22"（帶引號的字串）而不是數字或物件。包含時区的 2026-06-22T10:00:00+08:00 會保持為 ISO 8601 字串。

2. 多行字串（Multiline）

YAML 中保留換行的 |（literal block）和把換行折成空格的 >（folded block），轉成 JSON 後都會變成包含 \n escape 的單一字串。

description: |
  第一行。
  第二行。

轉換後會變成：

{
  "description": "第一行。\n第二行。\n"
}

確認換行位置是否如預期。

3. 錨點與別名（& / *）

YAML 的錨點（&id）和別名（*id）是用來重用同一個物件或值的語法。但 JSON 沒有「引用」的概念，別名指向的值會被展開成獨立副本。原本為了節省記憶體而設計的結構，在 JSON 中會變成檔案變大、且後續修改只影響其中一份副本。

4. 自訂語言 tag（!Ruby/Symbol 等）

Jekyll 的 Ruby symbol、PyYAML 的 !!python/object: 這類語言綁定 tag，在標準 JSON 中沒有對應表示法。大部分轉換器會報錯，或者直接忽略 tag 只保留純值。轉換前建議先檢查 frontmatter 中有沒有 ! 開頭的 tag。

5. 布林值誤推斷與「挪威問題」（Norway Problem）

YAML 1.1 規範中，除了 true/false，yes、no、on、off、y、n 也會被自動當成布林值。所以如果寫了 country: NO（挪威的國家代碼），轉換後會變成 country: false。這就是著名的「挪威問題」。

必須保持為字串的值，在 YAML 中一定要用引號包起來：country: "NO"。除了 frontmatter 的場景，一般 YAML 轉 JSON 還有哪些陷阱，可參考YAML 轉 JSON 指南。

實務工具比較：瀏覽器轉換 vs CLI / npm 套件

frontmatter 的 YAML 轉 JSON 工具各有適合的場景：

工具適合用途特色與限制
FormatArc YAML to JSON單份檔案確認、CMS payload 檢查、敏感資料純瀏覽器、不需安裝、不傳外部
gray-matter（npm）Node.js build script、Next.js / Astro pipelineYAML/TOML/JSON 全格式支援、同時回傳正文與元資料
markdown-to-json（npm）目錄批次轉換、產出 JSON 索引CLI 專用、以 YAML frontmatter 為主
python-frontmatter（PyPI）Python 資料分析、Jekyll 腳本YAML 為主要格式、TOML/JSON 為延伸
GitHub Actions workflowCI 上 PR 時批量驗證 frontmatter適合自動化、需先定義 schema

幾百份檔案要定期 build 的 CI/CD 環境用 CLI 套件；單次遷移檢查或處理外部洩漏禁止的內部機密檔案時，用瀏覽器工具比較合適。兩者互補而非競爭。

實務應用模式

1. Contentful / Strapi 遷移

如果 CMS 的 Content Model 欄位名稱跟 frontmatter 的 key 不一致，就需要在轉成 JSON 後寫映射 script，或手動調整 key 名稱再送進 API。

2. Notion 匯出的 Markdown 處理

Notion 匯出的 Markdown 檔案預設不包含 YAML frontmatter。可以先把 Notion 頁面屬性另外匯出成 JSON，再跟 Markdown 正文合併，或自行補上需要的元資料再組裝成 frontmatter。

3. CI pipeline 中的 JSON Schema 驗證

在部落格或技術文件儲存庫中，PR 合入前把 frontmatter 轉成 JSON 再用 ajv 等套件做 JSON Schema 驗證（檢查必填欄位、日期格式、tags 非空），是相當常見的 CI 步驟。

常見的坑

  • 正文的水平線（---）與 frontmatter 分隔線衝突：Markdown 正文中畫水平線如果用 ---，部分 parser 會誤認為 frontmatter 的結尾分隔線。正文中的水平線建議改用 *** 或 ___。
  • 全形冒號（：）輸入錯誤：用繁體中文輸入法打 : 時，不小心打出全形冒號 ：，YAML parser 不認它是 key 的分隔符，會產生語法錯誤。
  • 以 0 開頭的標識符（郵遞區號、工號等）：寫成 code: 01234 的話，YAML parser 可能把前導零丟掉變成 1234。要保持字串就寫 code: "01234"。

常見問題

frontmatter 可以直接寫 JSON 而不用 YAML 嗎？

如果你的 SSG 支援就可以。Hugo 和 Eleventy 預設接受 { ... } 格式的 JSON frontmatter。但 Astro、Jekyll、Gatsby、Docusaurus 等多數框架不認識 JSON frontmatter，如果要通用性還是保持 YAML。

Obsidian 的 frontmatter 也能轉 JSON 嗎？

可以。Obsidian 的 Properties 和 frontmatter 都是標準 YAML 格式，直接把開頭 --- 區塊複製貼到 YAML to JSON 就能正常轉換。

把分隔線 --- 也一起貼進轉換工具會出錯嗎？

取決於工具。YAML 規範中 --- 是合法的文件起始記號，但部分轉換 parser 處理不了最上層的分隔線，會回傳空物件。要穩定轉換的話，只貼分隔線內部的 YAML 本體就好。

用 FormatArc 轉換時資料會外洩嗎？

不會。FormatArc 的所有轉換都是在你的瀏覽器中用 JavaScript 執行，輸入的內容和轉換結果都不會上傳到任何外部伺服器。內部設定檔或未發布的文章都可以安全處理。

總結 — frontmatter 轉換 4 步驟

把 Markdown frontmatter 的 YAML 轉成 JSON，步驟整理如下：

  1. 從 Markdown 檔案中複製 --- 之間的 YAML 本體（不含分隔線）。
  2. 貼到 YAML to JSON，在瀏覽器中即時轉換。
  3. 檢查產出的 JSON 中日期、多行字串、布林值的型別是否正確。
  4. 把完成的 JSON 交給 headless CMS、build script 或 RAG pipeline。

如果需要反向操作，把 JSON 轉回 YAML frontmatter，可以用 JSON to YAML 工具。如果要確認目標 SSG 接受哪種格式，回上面那張對照表查一下。

frontmatter 背後的 YAML 語法細節、YAML 與 JSON 的型別差異，以及 Markdown 正文轉 HTML 的操作，都可以搭配 FormatArc 的其他工具一起使用：