Markdown の先頭にある frontmatter (--- で囲まれた YAML ブロック) を JSON にしたい場面は意外と多くあります。ヘッドレス CMS への流し込み、build script でメタ情報だけ抜き出して集計、別 SSG への移行、LLM に投入する前のコンテキスト整形などです。この記事では、Markdown 全文から frontmatter 部分だけを切り出して JSON に変換する手順を、SSG 別の対応表と壊れやすい型の注意点まで含めて整理します。
最短ルートは「Markdown を開く → 先頭の --- から次の --- までを抜き出す → YAML to JSON に貼り付ける」だけです。FormatArc はブラウザ内で変換が完結するので、社内 Wiki や非公開記事の frontmatter でも外部に送信されません。
結論: frontmatter は「区切り行 + YAML 本体」、変換は本体だけを渡す
frontmatter は次のように 3 行構造になっています。
---
title: "はじめての記事"
date: 2026-06-22
tags: ["intro", "demo"]
draft: false
---
本文の Markdown はここから書きます。
この上下の --- は YAML としては「ドキュメント区切り行」の意味を持ちますが、frontmatter のパーサに渡すときは中身だけを取り出すのが安全です。FormatArc の YAML to JSON ツールに上の例の中身 (タイトルから draft までの 4 行) だけを貼り付けると、次の JSON が返ります。
{
"title": "はじめての記事",
"date": "2026-06-22",
"tags": ["intro", "demo"],
"draft": false
}
タイトルが文字列、date が文字列、tags が配列、draft が boolean として正しく型付けされている点に注目してください。YAML の値の型推定は JSON への忠実な変換に直結します。
なぜ frontmatter を JSON にしたいのか — 4 つのユースケース
frontmatter の変換需要は次の 4 パターンに集約できます。どれに該当するかで、変換すべき範囲と注意点が変わります。
ヘッドレス CMS / API への流し込み
Contentful、Strapi、microCMS のような headless CMS は記事メタデータを JSON で扱います。社内で Markdown 運用していた記事を CMS に移行するとき、frontmatter を JSON に変換して REST/GraphQL の payload に組み込むのが定番のワークフローです。
build script でメタ情報だけ抜き出す
「投稿一覧 JSON」「タグ別記事数」「公開日順インデックス」のようなビルド成果物を生成するとき、本文を解析せず frontmatter だけを抽出して集計します。Node.js なら gray-matter、Python なら python-frontmatter を使うのが一般的です。
別 SSG への移行
Jekyll から Astro、Hugo から Next.js のように SSG を乗り換えるとき、frontmatter のキー名と型を確認しておく必要があります。Hugo の params.foo 形式を Astro が読めない、といった非互換は地味に多いです。
LLM への投入 (RAG / コンテキスト整形)
記事を ChatGPT や Claude の RAG に投入するとき、frontmatter を JSON 化して構造化メタデータとして渡すと、本文だけ渡すよりも検索精度と要約精度が上がります。タグ・カテゴリ・公開日が機械的に扱えるようになるためです。
frontmatter の 3 形式: YAML / TOML / JSON
frontmatter には実は YAML 以外の形式もあります。SSG によって受け入れる形式が異なるので、変換前に把握しておくと混乱が減ります。
YAML frontmatter (もっとも一般的)
---
title: "Hello"
date: 2026-06-22
---
区切りは 3 つのハイフン ---。Jekyll、Hugo、Astro、Eleventy など主要 SSG のほとんどが対応。
TOML frontmatter (Hugo / Zola で人気)
+++
title = "Hello"
date = 2026-06-22
+++
区切りは 3 つのプラス +++。Zola は TOML 必須、Hugo は YAML/TOML/JSON のいずれも可。
JSON frontmatter (Hugo / Eleventy などで対応)
{
"title": "Hello",
"date": "2026-06-22"
}
中括弧 { ... } 自体が区切りを兼ねます。Hugo と Eleventy はネイティブで読みますが、Astro と Jekyll は JSON frontmatter を受け付けません (Astro のドキュメントは YAML/TOML のみと明記)。
SSG 別の frontmatter 受け入れ形式マトリクス
主要な SSG が標準でどの frontmatter 形式を受け入れるかをまとめました。公式ドキュメント 2026-06 時点の確認です。
| SSG / Framework | YAML (---) |
TOML (+++) |
JSON ({...}) |
備考 |
|---|---|---|---|---|
| Hugo | はい | はい | はい | Org Mode (#+) も .org ファイルで対応 |
| Jekyll | はい | いいえ | いいえ | YAML 専用、空でも先頭 ---\n--- が必須 |
| Astro | はい | はい | いいえ | JSON frontmatter は変換が必要 |
| Eleventy (11ty) | はい | カスタム | はい | TOML は標準では非対応、プラグインで追加 |
Next.js + MDX (@next/mdx) |
デフォルト不可 | デフォルト不可 | デフォルト不可 | remark-frontmatter などの remark プラグイン追加が必要 |
| Gatsby | はい | いいえ | いいえ | gatsby-transformer-remark が YAML 前提 |
| VuePress | はい | いいえ | いいえ | YAML 専用 |
| Zola | いいえ | はい | いいえ | TOML 必須、移行時の YAML→TOML 変換が課題 |
| Docusaurus | はい | いいえ | いいえ | YAML 専用、gray-matter ベース |
このマトリクスから、変換が必要になる典型は次の 2 つです。
- Astro / Jekyll / Gatsby / Docusaurus に JSON frontmatter を渡したい: 受け付けないので必ず YAML へ変換する
- Zola へ Jekyll/Hugo (YAML) から移行する: 全記事の frontmatter を TOML に変換する必要がある
逆に Hugo と Eleventy は最も寛容で、既存の YAML/JSON 資産をそのまま流せます。
Markdown 全文から frontmatter 部分だけを切り出す
変換ツールに貼り付ける前に、Markdown 本文から frontmatter 部分だけを抜き出す必要があります。手順は単純です。
- 1 行目が
---であることを確認 (前に空行があると frontmatter として認識されないので注意) - 2 行目以降を読み、次に出てくる
---の行を探す - その 2 つの
---の間にある行 (上下の---自体は含めない) が YAML 本体
切り出した YAML 本体を YAML to JSON に貼ると JSON が返ります。FormatArc は変換処理がすべてブラウザ内で完結する設計なので、社外秘の記事や未公開コンテンツの frontmatter でも安全に扱えます。CLI ツールでまとめて変換すべき大量ファイルとは別に、「1 ファイルだけ確認したい」「CMS 投入前に payload を目視チェックしたい」用途では FormatArc が手早く済みます。
よくあるエラーパターン
- 「parse error: bad indentation」 — YAML のインデントがタブと半角空白で mix している。スペース統一で解消
- 「mapping values are not allowed here」 — 値の中にコロンが入っているのに引用符で囲んでいない。
title: "10:00 の打ち合わせ"のように"で囲む - 「could not find expected ':'」 — リストや配列の
-の後にスペースを忘れている
逆向き: JSON frontmatter を YAML に戻す
CMS から取得した JSON メタデータを Markdown frontmatter として書き出したい場合は、逆方向の変換が必要です。FormatArc の JSON to YAML ツールに JSON オブジェクトを貼り付けると YAML が返ります。
変換結果の YAML をそのまま frontmatter として使うには、上下に --- を足すだけです。
---
{ ここに YAML 変換結果が入る }
---
特に Astro / Jekyll / Gatsby など JSON frontmatter 非対応の SSG に既存 JSON 資産を持ち込む場面で必要になります。
YAML→JSON 変換で壊れやすい 5 つの型
YAML と JSON の型システムは似ていますが完全には一致しません。frontmatter 変換時に壊れやすい型を把握しておくと、デバッグが速くなります。
日付型 (date)
YAML 1.1 のパーサは 2026-06-22 を Date 型として解釈することがありますが、JSON には Date 型がないので文字列化されます。出力結果が "2026-06-22" のように引用符付きであることを確認してください。タイムゾーンを含む 2026-06-22T10:00:00+09:00 は ISO 8601 文字列としてそのまま保持されます。
複数行文字列 (multiline)
YAML の | (改行保持) と > (改行を空白に変換) を使った複数行文字列は、JSON では単一の文字列として \n でエスケープされます。意図と違う改行が入っていないか確認しましょう。
description: |
1 行目
2 行目
→
{ "description": "1 行目\n2 行目\n" }
アンカーとエイリアス (& / *)
YAML のアンカー (&id) とエイリアス (*id) は同じ値を共有するための仕組みですが、JSON にはこの概念がないので展開されてコピーされます。元の YAML で 1 箇所しか書いていない値が、JSON では複数箇所に複製されます。
カスタムタグ (!Ruby/Symbol など)
Jekyll の Ruby 由来のカスタムタグや、!!python/object: のような言語固有タグは JSON では表現できません。多くのパーサはエラーを吐くか、タグを無視して値だけを取り出します。
Unicode と引用符
YAML は ' (シングル) と " (ダブル) で引用符の挙動が違います。シングルは \n などのエスケープを文字通り扱い、ダブルはエスケープを解釈します。JSON はダブルクォート専用なので、シングルで囲まれた YAML 文字列は変換時にダブルに置き換わります。
CLI / npm パッケージとの使い分け
frontmatter の YAML→JSON 変換ツールはいくつかあります。それぞれに向き不向きがあるので、用途で使い分けます。
| ツール | 向いている用途 | 制約 |
|---|---|---|
| FormatArc YAML to JSON | 1〜数ファイルの確認、CMS 投入前の目視チェック、機密データの変換 | ブラウザ内のみ、自動化には不向き |
| gray-matter (npm) | Node.js での build script、Next.js の getStaticProps から呼ぶ | YAML/TOML/JSON すべて対応、本文と frontmatter を同時に返す |
| markdown-to-json (npm) | ディレクトリ単位での一括変換、JSON blob 生成 | CLI 専用、YAML frontmatter のみ |
| python-frontmatter (PyPI) | Python での記事処理、Jekyll サイトのスクリプト | YAML 中心、TOML/JSON はオプション |
| Frontmatter to JSON Converter (GitHub Action) | CI 上で frontmatter を JSON に変換し別 step で使う | 単一ファイルが基本、複数ファイルは別途ループ |
棲み分けの目安は「単発確認・機密データ・CMS 投入前のチェックは FormatArc、大量バッチ処理と CI 連携は CLI / Action」です。両者は競合ではなく補完関係にあります。
実用パターン: ヘッドレス CMS と Notion 移行
Contentful / Strapi への流し込み
CMS の Content Model に合わせた JSON 構造に変換して、API の POST 本体として送ります。frontmatter のキー名と CMS のフィールド名がずれる場合は、変換後の JSON を手動で書き換えるか、gray-matter の出力を mapping するスクリプトで吸収します。
Notion export からの取り込み
Notion からエクスポートした Markdown には簡易的な frontmatter が含まれません。社内で別途 frontmatter を付与してから JSON 化するワークフローが現実的です。Notion のページプロパティを別途 JSON でエクスポートし、後で merge する方が崩れません。
GitHub Action で frontmatter 一括チェック
required フィールドが揃っているか、date が ISO 形式か、tags が空配列でないか、といった検証は frontmatter を JSON に変換してから JSON Schema で検査するのが定番です。
よくある落とし穴
--- が文書末尾の HR と被る
Markdown の水平線 (HR) も --- で書けるので、本文末尾に HR を入れると frontmatter パーサが混乱することがあります。本文中の HR は *** か ___ を使うと安全です。
全角コロンと半角コロンの混在
日本語キーボードで : を入力するつもりが ： (全角コロン) になっていることがあります。YAML パーサは全角コロンを区切り文字として認識しないので「mapping values are not allowed」エラーになります。
インデントの mix-up
YAML はタブ文字をインデントとして使えません。タブが混ざると「found character that cannot start any token」エラーになります。エディタの設定で「タブをスペースに変換」を有効にしましょう。
Boolean の誤推定
YAML 1.1 では yes / no / on / off も Boolean として扱われます。country: NO (ノルウェー) と書くと country: false に化けます。文字列として保持したい場合は "NO" のように引用符で囲んでください。
まとめ — frontmatter 変換の最短手順
Markdown frontmatter の YAML を JSON に変換する手順をまとめると次の通りです。
- Markdown ファイルから
---で囲まれた YAML 本体だけを切り出す - YAML to JSON に貼り付ける (ブラウザ内で完結)
- 出力された JSON の型 (特に date / multiline / boolean) を確認する
- ヘッドレス CMS / build script / LLM 投入先に流し込む
逆向きが必要な場合は JSON to YAML で戻せます。SSG を移行するときは本記事の対応表で受け入れ形式を確認してから変換してください。
frontmatter の前提となる YAML 構文や JSON との違いについては、関連記事も合わせてどうぞ。
- YAML の書き方ガイド — YAML 構文の基礎
- YAML を JSON に変換する完全ガイド — frontmatter 以外の一般的な YAML→JSON 変換
- YAML と JSON の違い — どちらを選ぶか
- YAML とは — YAML の入門
- Markdown を HTML に変換するガイド — Markdown 本文側の変換
- CommonMark と GFM の違い — Markdown 方言の差