Published · June 28, 2026

YAML Front Matter Explained: Adding Metadata to Your Markdown Files

YAML front matter is the small block of metadata at the top of a Markdown file, fenced by triple dashes. It stores things like title, date, and tags without cluttering your text. Here's how the syntax works, which fields you'll actually use, and when front matter earns its place in your files.

Quick answer

YAML front matter is a small block of metadata at the very top of a Markdown file, wrapped between two lines of three dashes. It holds structured facts about the document — a title, a date, some tags — without those facts showing up in the rendered text. Static-site generators, documentation systems, and conversion tools read that block to decide how to handle the file. The body stays clean Markdown; the metadata rides along quietly above it.

How it actually works

Front matter is just YAML, and YAML is just key-value data. The block opens with a line containing exactly three dashes, lists your fields, then closes with another three-dash line. It has to be the first thing in the file — no blank lines, no stray characters above it — or most tools won't recognize it as metadata. This convention was popularized by Jekyll and is now standard across static-site generators and documentation platforms, including GitHub Docs.

The fences and the rules

A minimal block looks like this:

---
title: Getting Started with Plain Text
date: 2026-06-28
draft: false
---

Everything between the dashes follows YAML syntax. A few rules trip people up:

Indent with spaces, never tabs. YAML rejects tab characters outright, and a stray tab is the most common reason a block silently fails to parse.
Use key: value with a space after the colon.
Quote any value that contains a colon or a hash. title: "Notes: Q3 Planning" parses; the same line without quotes does not.

Common fields and data types

Most fields are plain strings, but YAML also understands lists, booleans, and dates. That lets a single block carry a surprising amount of structure:

---
title: Field Notes
author: Jane Rivera
date: 2026-06-28
tags: [markdown, plain-text, workflow]
published: true
---

The fields you'll meet most often are title, date, author, description, tags or categories, slug for a custom URL, layout to pick a template, and draft or published to control visibility. Tools differ on which keys they recognize, so the names you choose depend on what reads the file — a point worth checking against your generator's docs. If you're still getting comfortable with the body syntax underneath, our Markdown syntax cheat sheet covers the rest, and the differences between Markdown flavors explain why some keys behave differently from one tool to the next.

When to use it (and when to skip it)

Front matter earns its keep whenever a file needs to be more than prose. A blog post needs a title and a date. A documentation page needs a slug and a category. A note you want to find later benefits from a few tags. Because the metadata lives inside the file, the file stays self-contained and portable — move it to a new machine or a different tool and the context comes with it. Tools like Pandoc read the same block to carry a document's title and author across format conversions, so one Markdown file can become HTML, PDF, or a Word document without losing its metadata. It's also handy when writing a README that a static site will later render with its own template.

It's fair to skip it, too. A quick capture, a scratch file, or a throwaway list doesn't need a metadata header — adding one is just friction. Front matter is a tool for files that are managed, published, or organized at scale, not for every stray thought you jot down. And remember it isn't part of the Markdown standard itself; it's a convention layered on top, so a plain Markdown viewer with no front-matter support may show the raw dashes and keys at the top of the page.

How Carets fits in

Front matter is plain text sitting on top of plain text, which is exactly what Carets is built to edit. Carets is a fast, native notes and code editor for iPhone, iPad, and Mac that treats Markdown, plain text, and code as first-class citizens. The YAML block gets real syntax highlighting, so keys, values, and the fenced delimiters stay visually distinct from the prose below — easy to scan, easy to spot a malformed line. Because Carets keeps everything in plain files organized into projects and tags, a folder full of front-matter-topped Markdown stays browsable and portable, with nothing locked in a proprietary format. Your files remain yours, in a format that will still open years from now. Carets is on the App Store for iPhone, iPad, and Mac.

Frequently asked questions

Does YAML front matter show up in the rendered page?

No. Tools that understand front matter read the block as metadata and strip it before rendering. Readers see only the body below the closing dashes.

Why does my front matter break when I use tabs?

YAML forbids tab characters for indentation. Switch to spaces. Many editors can reveal invisible characters or convert tabs to spaces automatically, which usually fixes a block that refuses to parse.

Where exactly does the block have to go?

At the very top of the file, before anything else, fenced by a line of three dashes above and below. Even a single blank line above the opening dashes can stop a tool from recognizing it.

Is front matter part of the Markdown standard?

No. It's a widely adopted convention layered on top of Markdown, not part of CommonMark or GitHub Flavored Markdown. That's why support varies between tools.

Conclusion

YAML front matter is a small habit that pays off across a whole library of files: a tidy metadata header that keeps your Markdown organized, portable, and ready for whatever tool renders it next. Start with three fields — a title, a date, and a couple of tags — and add more only when a file actually needs them.