YAML vs TOML vs JSON frontmatter?

YAML is the most common (Hugo, Jekyll, Astro) — human-readable, supports comments. TOML is used by some tools (Zola) — stricter, less ambiguous. JSON is less common but universally parseable. Use YAML for most cases; use TOML if you want strict parsing.

Can frontmatter contain Markdown?

Yes, but it must be quoted or use YAML block scalars (| for literal, > for folded). For example: description: | This is a **long** description with _Markdown_. Parse this field as Markdown in your template.

TASK

Use YAML frontmatter for document metadata

Frontmatter is YAML metadata at the top of a Markdown file, delimited by ---. Common in static site generators (Astro, Hugo, Jekyll) for page metadata.

1

Frontmatter is a YAML block at the top of a file, delimited by --- on the first line and before the content. It contains metadata (title, date, tags, layout) that is parsed separately from the Markdown body. Static site generators use it to drive templates, routing, and collections.
2

YAML Converter →
Parse the frontmatter YAML to verify valid syntax. Common fields: title (string), date (ISO 8601), tags (array), draft (boolean), layout (string). YAML errors in frontmatter will prevent the page from building — validate early.
3

Markdown HTML Converter →
Parse the Markdown body (after the frontmatter) to HTML. The frontmatter and body are processed separately: YAML metadata for templates, Markdown for content. This separation enables data-driven page generation.
4

Best practices: use consistent field names across all pages, use ISO 8601 dates (2024-01-15 or 2024-01-15T10:30:00Z), use arrays for tags and categories, use booleans for draft/featured flags. Define a schema (Zod, JSON Schema) and validate at build time to catch missing or invalid fields.

Frequently asked questions

YAML vs TOML vs JSON frontmatter?: YAML is the most common (Hugo, Jekyll, Astro) — human-readable, supports comments. TOML is used by some tools (Zola) — stricter, less ambiguous. JSON is less common but universally parseable. Use YAML for most cases; use TOML if you want strict parsing.
Can frontmatter contain Markdown?: Yes, but it must be quoted or use YAML block scalars (| for literal, > for folded). For example: description: | This is a **long** description with _Markdown_. Parse this field as Markdown in your template.