Markdownのfrontmatterエラーを直す｜区切り・日付・引用符のよくあるミス

Markdown記事を追加した直後にビルドが止まったら、本文より先にファイル冒頭のfrontmatterを確認します。frontmatterのエラーは、YAMLとして読めない「構文エラー」と、読めてもサイトが求める項目や型に合わない「schemaエラー」に分けると切り分けやすくなります。

この記事では、原因を2種類に分け、上から順に確認する手順を示します。Astroで記事コレクションを作る流れそのものは、別の記事で扱います。

frontmatterの役割

frontmatterは、Markdown本文の前に置く記事データです。タイトル、説明文、公開日、タグなどをYAML形式で記録します。AstroのContent Collectionsではschemaを定義し、各記事の項目が同じ形かを検証できます。

まずエラーメッセージを見て、調べる場所を絞ります。

エラーの種類	メッセージの例	最初に見る場所	よくある原因
YAMLの構文エラー	Failed to parse Markdown frontmatter	エラー行と直前の行	区切り線、コロン、引用符、字下げ
schemaエラー	data does not match schema	src/content.config.*と既存記事	必須項目の欠落、項目名や型の不一致
直した後も同じ表示	同じファイル・同じ項目が再表示される	保存状態と開発サーバー	未保存、別ファイルを編集、schema更新の未反映

構文エラーの行番号は解析が止まった場所であり、原因が直前の行にある場合もあります。schemaエラーでは、同じコレクションの既存記事とschema定義を並べて比較します。Astro公式も、必須項目と型をsrc/content.config.*のschemaで確認するよう案内しています。

最小構成は次の形です。実際に必要な項目名は、同じサイトの既存記事とsrc/content.config.*などのschema定義を正本にしてください。

---
title: '記事タイトル'
description: '記事の説明'
pubDate: 2026-07-23
draft: true
tags: ['Markdown', 'YAML']
---

1. 区切り線の欠落を直す

frontmatterの開始と終了には、行全体が半角ハイフン3個の---になった区切り線を置きます。終了側を忘れると、本文の見出しまでYAMLとして読もうとして解析に失敗します。全角の－－－、ハイフン2個、行頭の空白、同じ行に付けたコメントも避けます。

 ---
 title: '記事タイトル'
 pubDate: 2026-07-23
+---
 
 ## 記事本文

1行目から開始、YAMLの項目、終了、空行、本文の順へ揃えます。区切りが正しければ、閉じていない引用符や値のない行を探します。Astro公式のエラー例にも、コロンの欠落や二重引用符の閉じ忘れがあります。

2. コロンと引用符を確認する

YAMLのマッピングはキー: 値で表します。そのため、タイトルや説明文に:と半角空白が含まれると、値の途中を新しい対応関係として誤解されることがあります。URL、時刻、注意: 保存前に確認のような文字列は、値全体を引用符で囲むのが安全です。

-title: エラー対処: 保存前に確認する
+title: 'エラー対処: 保存前に確認する'

YAML 1.2.2では、プレーンな文字列中のコロンは直後に空白がなければ使えます。一方、注意: 保存前に確認のようにコロンの直後が空白だと構造との区別が難しくなるため、文章を引用符で囲むと意図が明確です。

単一引用符の中の'は''と2個続けます。二重引用符では\nなどがエスケープとして解釈されるため、Windowsのパスには注意します。解析位置の読み方は、別の記事で扱います。

3. 日付形式をschemaへ揃える

日付は見た目が同じでも、読み込み側のschemaが文字列を求めるか、日付へ変換するかで合否が変わります。まず既存記事とschemaを確認し、サイト内で一つの形式に揃えます。年月日だけなら、次のようなYYYY-MM-DD形式が比較しやすい書き方です。

pubDate: 2026-07-23

時刻まで必要なら、タイムゾーンを含むISO 8601形式など、プロジェクト所定の形式を使います。YAMLの型解釈は処理系やschemaに依存します。schemaがz.string()なら'2026-07-23'のような文字列を、z.coerce.date()なら変換できる入力を使い、実際の検査コマンドで確かめます。Zodのz.coerceは入力を目的の型へ変換しようとする仕組みであり、どの文字列でも有効な日付になるという意味ではありません。pubDateとpubdateのような表記差にも注意してください。

4. 配列と真偽値を確認する

タグなど複数の値は配列、公開状態など二択の値は真偽値として書きます。文字列との取り違えを避けるため、同じコレクション内で表記を統一します。

tags:
  - Markdown
  - YAML
draft: true

短い配列ならtags: ['Markdown', 'YAML']でも表せます。ブロック形式では各要素の-を同じ深さへ揃え、空白で字下げします。tags: Markdown, YAMLは一つの文字列です。

真偽値は、互換性と読みやすさのためtrueまたはfalseを小文字・引用符なしで書くのが無難です。'true'は文字列です。YAML 1.2.2のCore Schemaでは大文字を含む表記も真偽値として解決されますが、プロジェクト内では既存記事の表記へ統一します。Astroのschemaがz.array(z.string())やz.boolean()を求めるなら、frontmatter側も文字列の配列と真偽値に合わせます。

5. 最小差分で直して再検査する

1件を直したら、同じミスが他の記事にもないかローカルで検査します。サイト既定の検査コマンドを実行し、対象ファイル名と項目名を控えます。一括置換より先に、1件で合格する最小差分を確認してください。

PowerShellでは、構文を解析する前の簡易確認として、frontmatterの開始行や必須キーの候補を検索できます。

Get-ChildItem 'src/content/articles' -Filter '*.md' |
  Select-String -Pattern '^---$|^title:|^pubDate:|^draft:'

この検索だけではYAMLの妥当性もschema適合も保証できません。最後はAstroの型検査やプロジェクト独自の検算を実行し、終了コードを確認します。エラーが複数なら最初の1件を直して再実行します。schema自体を更新した直後は、Astro公式の案内どおり開発サーバーの再起動やContent Layerの同期が必要になる場合があります。

記録には「対象ファイル」「最初のエラー文」「直した項目」「実行した検査」を残してください。schema側の原因の切り分けは、別の記事で扱います。

よくある質問

frontmatterの---は本文中でも使えますか

本文中では水平線として扱われることがあります。frontmatterの区切りとして重要なのは、ファイル先頭の開始行とメタデータ直後の終了行です。まず冒頭2本の位置を確認してください。

エラーに表示された行を直しても解決しないのはなぜですか

閉じていない引用符や字下げのずれなど、直前の行が原因のことがあります。表示行だけでなく、その1〜3行前まで確認し、一度に複数箇所を変えず再検査します。

draft: 'true'とdraft: trueは同じですか

同じではありません。前者は文字列、後者は真偽値です。schemaがz.boolean()を求める場合は、引用符なしのtrueまたはfalseにします。

日付は引用符で囲むべきですか

一律には決まりません。z.string()、z.date()、z.coerce.date()などschemaの定義によって期待される入力が異なるため、既存記事とsrc/content.config.*を正本にします。

YAMLとして正しいのにAstroで失敗するのはなぜですか

YAMLの解析に成功しても、必須項目の欠落や型の不一致があればschema検証で失敗します。エラー文にschemaや具体的な項目名があれば、YAMLの記号より先にschema定義と値の型を比較してください。

---

一次情報の確認メモ（2026-07-24確認）

• Markdown in Astro（Astro公式）: YAMLまたはTOMLのfrontmatterと基本例
• Failed to parse Markdown frontmatter（Astro公式）: コロンの欠落や引用符の閉じ忘れによる解析失敗
• Content collections（Astro公式）: schemaによる検証、Zodの型、schema更新後の再起動・同期
• Content entry data does not match schema（Astro公式）: 必須項目と型がschemaに合わない場合の確認先
• YAML 1.2.2仕様（YAML Language Development Team）: マッピング、配列、コロン、引用符、真偽値の仕様
• Defining schemas（Zod公式）: z.coerceによる入力値の型変換