ドキュメントのメタデータに YAML フロントマターを使う
フロントマターは Markdown ファイル先頭の「---」で区切られた YAML メタデータです。静的サイトジェネレーター(Astro、Hugo、Jekyll)でページメタデータとしてよく使われます。
- 1
Frontmatter はファイル先頭にある YAML ブロックで、1 行目と本文の直前に --- で区切られます。ここにはメタデータ (title、date、tags、layout) が含まれ、Markdown 本文とは別々にパースされます。静的サイトジェネレーターはこれをテンプレート、ルーティング、コレクションの駆動に利用します。
- 2 YAML コンバーター →
Frontmatter の YAML をパースして、構文が正しいかを確認します。よく使われるフィールドは title (文字列)、date (ISO 8601)、tags (配列)、draft (真偽値)、layout (文字列) です。Frontmatter 内の YAML エラーはページのビルドを妨げるため、早めに検証してください。
- 3 Markdown HTML コンバーター →
Markdown 本文 (frontmatter より後の部分) を HTML にパースします。Frontmatter と本文は別々に処理されます。YAML メタデータはテンプレート用、Markdown はコンテンツ用です。この分離により、データ駆動のページ生成が可能になります。
- 4
ベストプラクティス：すべてのページでフィールド名を統一する、ISO 8601 形式の日付 (2024-01-15 または 2024-01-15T10:30:00Z) を使う、tags や categories には配列を使う、draft/featured フラグには真偽値を使うことです。スキーマ (Zod、JSON Schema) を定義してビルド時に検証し、欠落や不正なフィールドを検出してください。
よくある質問
- YAML、TOML、JSON の frontmatter の違いは？
- YAML が最も一般的です (Hugo、Jekyll、Astro)。人間が読みやすく、コメントをサポートしています。TOML は一部のツール (Zola) で使われ、より厳密で曖昧さが少ない形式です。JSON はあまり使われませんが、どの環境でもパースできます。ほとんどの場合は YAML を、厳密なパースが必要な場合は TOML を使ってください。
- Frontmatter に Markdown を含められますか？
- はい。ただし、引用符で囲むか、YAML のブロックスカラー (| はリテラル、> は折り返し) を使う必要があります。例：description: | これは _Markdown_ を含む**長い**説明文です。テンプレート側でこのフィールドを Markdown としてパースします。