Front Matter — YAML, TOML, JSON at the Top

The metadata block above the body

Front matter is a structured-data block at the very top of a Markdown file that holds metadata — title, date, tags, draft status. Static-site generators (Hugo, Jekyll, Astro, Next MDX, Eleventy) read the front matter to drive routing, sorting, indexing, and rendering. Below the front matter, the file is normal Markdown.

Three flavors

YAML — fenced by --- on a line by itself. Most common. Jekyll, Hugo, Astro, Next MDX, Pelican, Gatsby.
TOML — fenced by +++. Hugo's preferred flavor. Easier to read with quotes-around-strings discipline.
JSON — usually fenced by ;;; or written as a literal { ... } block. Less common; some MDX setups support it natively.

Common keys (convention, not spec)

title, date, slug, tags, categories, draft, author, cover. Each generator extends with its own (weight in Hugo, layout in Jekyll, permalink, etc.). Read your generator's docs for the canonical list.

The Norway Problem in YAML front matter: tags: [no, yes, on, off] in YAML 1.1 parses as [false, true, true, false]. Always quote string-typed values that look like keywords: tags: ["no", "yes"]. The YAML track will go deep on this.

Code

YAML front matter (most common)·markdown

---
title: "My First Post"
date: 2026-05-04
tags: [markdown, intro, gfm]
draft: false
---

# My First Post

The body of the document is normal Markdown.

TOML front matter (Hugo's flavor)·markdown

+++
title = "My First Post"
date = 2026-05-04
tags = ["markdown", "intro", "gfm"]
draft = false
+++

# My First Post

The body of the document is normal Markdown.

JSON front matter (some MDX setups)·markdown

;;;
{
  "title": "My First Post",
  "date": "2026-05-04",
  "tags": ["markdown", "intro", "gfm"],
  "draft": false
}
;;;

# My First Post

Exercise

Take a Markdown file from any of your projects (a README, a journal entry, a blog draft) and write three versions of its front matter — one YAML, one TOML, one JSON. Render them with the same generator (Hugo or Astro) and see what each produces. Pick the one you'll commit to going forward, and document why.

Front Matter — YAML, TOML, JSON at the Top

The metadata block above the body

Three flavors

Common keys (convention, not spec)

Code

External links

Exercise

Progress

Comments 0