YAML Front Matter Guide

What the --- block at the top of a file is, and how to write it so parsers never complain.

What front matter is

Front matter is metadata placed at the very top of a file, separated from the actual content by --- delimiters. When that metadata is written in YAML, it is called YAML front matter. Because it is YAML, it supports lists, nested keys, and typed values — which is exactly why it is so popular.

Who uses it

Static site generators — Hugo, Jekyll and Astro read page metadata (title, date, layout, tags) from front matter.
Note apps — Obsidian stores its properties in YAML front matter.
CI and docs — GitHub and GitLab parse YAML front matter from issue templates, workflow files and certain Markdown docs.

The anatomy of a block

---
title: My Post
date: 2026-08-21
tags:
  - yaml
  - guide
draft: false
---
# The real content starts here

Three rules make almost every block valid:

Open and close with --- on its own line.
Use key: value with a space after the colon.
Indent nested values with 2 spaces — never tabs.

Lists vs comma strings

A list is a set of dashed, indented items:

tags:
  - yaml
  - guide

The inline form is also valid:

tags: [yaml, guide]

But tags: yaml, guide is a single string — not what most tools expect.

Validate it before publishing

The fastest way to confirm a block is well-formed is the YAML frontmatter validator. It pastes a whole file, extracts only the --- block, and reports the exact line of any error. It runs entirely in your browser, so private drafts never leave the page.

For the underlying syntax, see What is YAML? and the indentation guide.

FAQ

What is front matter?

Front matter is a block of metadata placed at the top of a file, separated from the content by --- delimiters. In the YAML variant it is written in YAML, so it supports lists, nested keys and typed values.

Which tools use YAML front matter?

Static site generators such as Hugo, Jekyll and Astro use it for page metadata, and note apps such as Obsidian store their properties there. GitHub and GitLab also read YAML front matter from certain files.

How do I write valid YAML front matter?

Open with --- on its own line, write keys with a colon and a space, indent nested values with 2 spaces (never tabs), keep lists as dashed items, then close with --- on its own line.

Keep reading

Obsidian YAML front matter — the six errors Obsidian users hit.
Hugo vs Jekyll front matter — generator-specific differences.
YAML frontmatter validator — check any block in the browser.