What is YAML front matter?

A block of metadata at the very top of a Markdown file, fenced by a line of three dashes above and below. It holds things about the document — title, date, tags — rather than content, and the tool that processes the file reads it and strips it before rendering.

Where exactly does it have to go?

The opening --- must be the first line of the file. Not the second, and not after a blank line or a byte order mark. Anywhere else and it is not front matter; it is a horizontal rule followed by some text that happens to have colons in it.

Why did my front matter break?

Almost always a colon followed by a space inside an unquoted value. In YAML that starts a new key, so title: Markdown: a guide is a parse error. Quote the value, or use a block scalar for anything long.

Most static site generators — Jekyll, Hugo, Astro, Eleventy, Gatsby, Zola — and note apps including Obsidian, which surfaces it as properties. Each defines its own field names, so check what yours expects before adding fields it will ignore.

What are the +++ and ;;; variants?

Different languages inside the same idea. Three plus signs fence TOML, which Hugo supports, and some tools accept JSON. YAML between three dashes is by far the most common and the safest default.

What happens to front matter here?

The editor recognises it, hides it from the preview, and shows a small note saying how many lines it skipped — so you can see it is being read correctly without it cluttering the rendered document. It stays in the file and in every export.

YAML front matter

Front matter is a block of metadata at the very top of a Markdown file, fenced by three dashes. It describes the document — title, date, tags — and the tool that processes the file reads it and strips it before anyone sees the page.

Edit the block — the preview hides it and says how many lines it skipped

Markdown

Result

Runs entirely in this tab. Open the full editor to work on a real document.

The rules that actually matter

It must start on line one. The opening --- has to be the first thing in the file — not after a blank line, not after a comment. Anywhere else and the parser sees a horizontal rule followed by some odd-looking text, which is why a document sometimes renders with its metadata visible at the top.

Colons need care. In YAML, a colon followed by a space separates a key from a value, so a value containing one breaks the parse:

title: Markdown: a guide      # error
title: "Markdown: a guide"    # fine

This is the single most common failure, and the error message is rarely helpful about it. Quoting every string value costs nothing and avoids the whole class of problem.

Indent with spaces, never tabs. YAML rejects tabs for indentation outright. An editor that inserts a tab silently is the usual culprit when a nested block will not parse.

Long values

For anything that runs past a line, use a block scalar rather than fighting the quoting rules:

description: >-
  A folded block. Newlines become spaces, so this
  ends up as one long line, and colons: like this
  one are no longer a problem.

body: |
  A literal block. Line breaks
  are kept exactly as written.

Which fields to use

There is no standard set. Each tool defines its own: Jekyll wants layout, Hugo has draft and weight, Astro validates whatever schema you declare, and Obsidian surfaces every key as a property. Adding fields your tool does not read is harmless but pointless — check its documentation rather than copying a block from elsewhere.

In practice title and date are near-universal; description, tags and draft are common. A draft flag is worth adopting even if nothing reads it yet: it is a one-word switch that stops half-finished work publishing itself.

The other fences

Three plus signs fence TOML instead of YAML, which Hugo accepts; some tools also take JSON. They exist because YAML's whitespace rules annoy people. YAML between three dashes remains the most widely understood, and is the right default unless your generator says otherwise.

How this editor treats it

Front matter is recognised, hidden from the preview, and replaced with a small note saying how many lines were skipped — enough to confirm it parsed without it dominating the page. It stays in the file, and in the .md export. Exports to PDF and Word omit it, since it is not part of the document anyone is meant to read.

Common questions

What is YAML front matter?: A block of metadata at the very top of a Markdown file, fenced by a line of three dashes above and below. It holds things about the document — title, date, tags — rather than content, and the tool that processes the file reads it and strips it before rendering.
Where exactly does it have to go?: The opening --- must be the first line of the file. Not the second, and not after a blank line or a byte order mark. Anywhere else and it is not front matter; it is a horizontal rule followed by some text that happens to have colons in it.
Why did my front matter break?: Almost always a colon followed by a space inside an unquoted value. In YAML that starts a new key, so title: Markdown: a guide is a parse error. Quote the value, or use a block scalar for anything long.
Which tools read it?: Most static site generators — Jekyll, Hugo, Astro, Eleventy, Gatsby, Zola — and note apps including Obsidian, which surfaces it as properties. Each defines its own field names, so check what yours expects before adding fields it will ignore.
What are the +++ and ;;; variants?: Different languages inside the same idea. Three plus signs fence TOML, which Hugo supports, and some tools accept JSON. YAML between three dashes is by far the most common and the safest default.
What happens to front matter here?: The editor recognises it, hides it from the preview, and shows a small note saying how many lines it skipped — so you can see it is being read correctly without it cluttering the rendered document. It stays in the file and in every export.