Published · September 12, 2026

YAML Front Matter in Markdown: What It Is and How to Use It

YAML front matter is a fenced block of key-value metadata at the top of a Markdown file — titles, dates, tags — that tools read separately from the body. Here's the syntax, the common pitfalls, and when it's worth adding.

Quick answer

Markdown YAML front matter is a block of key-value metadata — title, date, tags, whatever you need — fenced by two lines of three hyphens (---) at the very top of a file. A static site generator, note tool, or build script reads that block on its own, separate from the body. The result: structured metadata without cluttering the prose people actually came to read.

How it actually works

The convention was popularized by Jekyll, and it stuck. Most static site generators, documentation systems, and note apps that support Markdown now expect the same shape at the top of a file.

A front matter block is just a YAML mapping, wrapped in delimiters. Simple in theory. It opens with a line containing exactly ---, and that line can't be followed by a blank line — the parser needs the metadata to start right away. Pandoc will close a block with either --- or three dots (...); CommonMark and GitHub Flavored Markdown are stricter, recognizing only --- for both fences, and only when the block sits at the very beginning of the file.

Inside the fences, it's ordinary YAML: key-value pairs separated by a colon and a space, nested objects expressed through indentation, and lists written as dash-prefixed items. A typical block for a blog post looks like this:

---
title: "Migrating Config Files Without Losing Comments"
date: 2026-09-12
tags:
  - config
  - yaml
draft: false
---

Two rules cause most of the errors people hit. First, an unquoted colon inside a value gets read as a second key-value separator — title: My Guide: A Primer breaks past the second colon, so wrap the whole value in double quotes instead. Second, a single quote inside a single-quoted string needs to be doubled ('It''s here') to escape it. And a long multi-line value? Easier to write with YAML's literal block style (|) than with manual line breaks and escaping.

Not every parser agrees on how strict to be about placement, either. See GFM vs. Pandoc syntax differences for another spot where the two dialects diverge, and why Markdown strips raw HTML for a related case of a renderer enforcing rules the plain-text file doesn't show you.

When to use it (and when to skip it)

Add front matter when something downstream actually reads it: a static site generator building pages from a title and date, a feed generator pulling tags, or a team that wants consistent, machine-readable metadata across a folder of files instead of guessing from filenames. If nothing parses the block, it's just ceremony — a scratch note or a one-off snippet doesn't need it.

Worth knowing before you copy a front matter pattern from one tool to another: Pandoc tolerates multiple metadata blocks in a document and merges them, with the last one winning on duplicate keys. CommonMark and GFM don't — one block, at the top, full stop. If your files move between a Pandoc-based pipeline and a GFM-rendering site, keep the block simple and singular so it behaves the same everywhere. For other spots where Markdown dialects quietly disagree, see other Markdown extras editors skip.

Frequently Asked Questions

Does front matter have to start with three dashes?

Yes, in every implementation that matters for Markdown authoring. The opening line is exactly three hyphens (---) with nothing else on it, and it can't be followed by a blank line. Pandoc and most static site generators accept a closing --- or three dots (...); CommonMark and GitHub Flavored Markdown only recognize --- as both the opening and closing fence, and only at the very top of the file.

Can front matter contain nested data, not just flat key-value pairs?

Yes. Front matter is a full YAML mapping, so it supports nested objects and lists — a tags list, or an authors list where each entry is itself a small object with a name and a role. Indentation is what establishes the nesting, so keep it consistent (2 or 4 spaces, never tabs) or the parser will misread the structure.

Why does my build fail on a title with a colon in it?

YAML treats an unquoted colon-plus-space as a key-value separator, so title: My Guide: A Primer reads as invalid syntax past the second colon. Wrap the whole value in double quotes (title: "My Guide: A Primer") and the parser treats it as one string.

Is YAML front matter the only option in Markdown files?

No — TOML and JSON front matter exist and some tools support them, but YAML is by far the most common, largely because Jekyll popularized it and most static site generators and note tools copied the convention. Sticking with YAML keeps a file portable across the widest range of tools.

How Carets fits in

Carets keeps files as plain Markdown, so a front matter block you write stays exactly as you wrote it — no proprietary reformatting, no silent rewriting of your YAML when you sync between iPhone, iPad, and Mac. Carets is native and fast, built for iOS and Mac rather than a web wrapper, so opening a file full of front matter and a long body doesn't cost you a loading spinner.

The block itself gets the same syntax highlighting as any other code in Carets, so the --- fences and YAML keys stand out from the prose below them, and mistakes like an unquoted colon are easier to spot before you save. Files, projects, and tags in Carets also mean you don't need front matter to do organizational work the app already does natively — keep the block focused on what your build tool actually reads, and use Carets' own tags and projects for everything else.

Carets is a fast, native notes and code editor for iPhone, iPad, and Mac — Markdown, plain text, and code with syntax highlighting, organized into files, projects, and tags. Download Carets on the App Store for iPhone, iPad, and Mac.