Markdown frontmatter パース / 生成

frontmatter が含む情報の種類

SSG (静的サイトジェネレーター) の frontmatter には記事のメタデータが集中しています。title・date・tags は当然として、author・draft: true・internal: true のような下書き・非公開フラグ、slug や permalink による URL 設計、weight・order・featured による掲載優先順位、場合によっては password フィールドや access_level のような権限情報が含まれることがあります。

未公開の記事・ブログの下書き・社内 Wiki のページを扱う場面では、frontmatter を解析して確認したい需要があります。これらのコンテンツはまだ公開されていない情報を含んでいるため、確認のためにオンラインツールに送ることは、未公開コンテンツを外部サーバーに渡すことになります。

未公開コンテンツをオンラインツールで処理するリスク

Markdown ファイルの frontmatter を解析・編集するオンラインツールに対してファイル内容を送信すると、記事の本文を含む全体がサーバーに届きます。下書き段階のブログ記事・未発表の技術文書・社内ナレッジベースのページは、公開前の段階で第三者に知られることを想定していません。

さらに compose モードでは frontmatter と本文を組み合わせて Markdown を生成する作業が発生します。frontmatter の YAML と本文の両方を貼り付けることになるため、コンテンツの全体像が外部に渡ります。Hugo・Astro のプロジェクトで複数のページを一括で frontmatter 操作する作業では、多数のページの内容が対象になることがあります。

eemeli/yaml ライブラリでブラウザ内に閉じる

このツールは eemeli/yaml ライブラリをブラウザバンドルとして読み込み、YAML の解析をブラウザ内で実行します。RFC 5545 準拠の YAML 1.2 型 (string / number / boolean / null / array / object / date) の解析、行番号付きのエラーメッセージの生成、JSON 表現へのシリアライズはすべてクライアントサイドで完結します。compose モードの --- フェンス挿入・frontmatter と本文の結合も JavaScript で処理します。

入力した Markdown ファイルの内容はページメモリにのみ存在します。未公開の記事・下書き・社内文書を安全に解析・編集できます。

SSG 移行やコンテンツ品質チェックへの活用

Hugo から Astro への移行・Jekyll から Next.js MDX への移行では、frontmatter の構造が変わることがあります。このツールで既存の frontmatter を JSON 形式で確認し、必要なフィールドの有無・型・値を確認してから移行スクリプトを書く、という作業に使えます。draft: true のフラグが付いたまま本番ビルドに混入していないか確認する、date フィールドの形式が統一されているか確認する、といった品質チェックにも活用できます。frontmatter の YAML 自体を JSON 化したい場面では yaml-json-convert が、本文の見出し構造を整えたい場合は markdown-toc が次のステップになります。

YAML 1.2 仕様と frontmatter 慣習: --- フェンスの起源と TOML / JSON 派生

Frontmatter という呼称は Jekyll が 2008 年に YAML ベースのメタデータブロックを --- フェンスで囲む形式を採用したことに由来し、その後 Hugo・Hexo・Gatsby・Astro・Next.js MDX が同じ慣習を継承しました。YAML 自体は IETF / YAML.org の YAML 1.2 仕様 (2009 年公開、現行は 2021 改訂版) で定義され、本ツールが使う eemeli/yaml ライブラリ (npm 名 yaml) は YAML 1.2 / 1.1 両対応のフル準拠 parser です。json-to-yaml の単純な変換ではなく、行番号付きエラー・コメント保持・anchor / alias / tag による参照を解釈できます。

frontmatter は YAML が主流ですが、TOML 派生 (Hugo の +++ ... +++)・JSON 派生 ({ ... } ブロック)・Org-mode (#+TITLE: 形式) なども実装によっては使われます。Astro Content Collections は zod スキーマで frontmatter を runtime バリデーションし、型安全な MDX を要請するため、本ツールで JSON 形式の解析結果を得た後に zod スキーマと突合する流れが想定されます。gray-matter (Node 用 frontmatter パーサ) も同じ --- フェンス慣習を採用しており、出力の JSON 形は本ツールと互換です。

YAML の闇: ノルウェー問題 / オクテット混入 / アンカーループ

YAML 1.1 には「ノルウェー問題」と呼ばれる悪名高いバグがあります。country: NO を ISO 国コードのつもりで書くと、YAML 1.1 では NO が boolean false の別名として解釈され (yes/no/on/off/true/false がすべて bool)、結果として country: false になります。YAML 1.2 でこの bool エイリアスは true / false のみに削減されましたが、古いツール (Ruby の Psych 旧版・Python の PyYAML デフォルト) は依然として 1.1 動作のため、NO OFF Y N を文字列として扱いたい場合は明示的にクォート (country: "NO") する必要があります。eemeli/yaml は YAML 1.2 がデフォルトなのでこの問題は出ませんが、別の parser に渡したときに値が変わる可能性があります。

もう 1 つの罠は anchor (&id) / alias (*id) の循環参照と「YAML billion laughs 攻撃」(DoS 攻撃)、そしてタブ文字の混入です。YAML はインデントにタブを禁じており、エディタの設定で \\t が混ざると unexpected character で parse 失敗します。gray-matter などのパーサは frontmatter の YAML が壊れていると body だけを返す挙動 (silent fallback) を取ることがあるため、frontmatter が抜け落ちて公開してしまう事故もあります。本ツールはエラーを明示的に表示するため、CI 前の検証ステップとして使うのが安全です。date: 2024-01-01 のような ISO 8601 日付は YAML 1.2 では自動で Date オブジェクトになる (JSON シリアライズ時は文字列に戻る) ため、date: "2024-01-01" と文字列として保ちたいときはクォートを付けてください。