If you've opened a Markdown file and seen a block like this at the top, you've already met YAML frontmatter:
---
title: "Blogging Like a Hacker"
date: 2026-08-12
tags:
- markdown
- writing
---
It looks small, but it's doing a specific job: separating a file's metadata (title, date, tags, status) from its content (the actual writing below it), so tools can read the metadata without having to parse the prose. This post explains what YAML frontmatter is, how to write it correctly, where you'll run into it, and the mistakes that most often break it.
What Is YAML Frontmatter?
Frontmatter is a block of structured data placed at the very top of a text file, before the main content. When that block is written in YAML (a human-readable data format built around indentation and key: value pairs), it's called YAML frontmatter.
The convention was popularized by the static site generator Jekyll, which uses a YAML block wrapped in triple-dashed lines (---) to attach variables like layout, title, and date to a page. According to GitHub's own documentation for its Docs site, which also runs on YAML frontmatter, the format is "an authoring convention popularized by Jekyll that provides a way to add metadata to pages."
Since then, the same pattern has spread far beyond Jekyll. Any tool that processes Markdown files and needs to know something about the file — not just its text — tends to reach for a YAML block at the top, because it's easy to write by hand and easy to parse programmatically.
Basic Syntax: How to Write YAML Frontmatter
The triple-dash delimiters
Frontmatter starts and ends with a line containing exactly three hyphens:
---
title: My First Post
---
Everything between the two --- lines is parsed as YAML. Everything after the closing --- is treated as the file's regular content (Markdown, in most cases). The opening --- must be the very first line in the file — nothing, not even a blank line, can come before it.
Key: value pairs
The core building block is key: value, with a space after the colon:
title: How to Write Frontmatter
published: true
views: 1024
YAML infers the type automatically: true/false become booleans, unquoted numbers become numbers, and everything else is treated as a string. If a string contains a colon, a leading #, or other characters YAML treats as special, wrap it in quotes to avoid a parse error:
title: "Docker vs. Podman: What's the Difference?"
Lists and nested values
Lists use a hyphen for each item, indented under the key:
tags:
- markdown
- seo
- indie-hackers
You can also nest key/value pairs, as long as indentation is consistent (YAML uses spaces, never tabs, to represent nesting):
author:
name: Jordan Lee
url: https://example.com
Two spaces per indentation level is the most common convention, though the exact number matters less than consistency — mixing tabs and spaces, or shifting indentation mid-block, is one of the most common ways frontmatter breaks (more on that below).
Where YAML Frontmatter Shows Up
The format is the same everywhere; what changes is which keys each tool actually reads.
Static site generators
Jekyll, Hugo, Astro, Docusaurus, Eleventy, and VitePress all read a YAML (or in some cases TOML) block at the top of each Markdown or MDX file to determine the page's title, layout, publish date, and other settings. The specific keys differ by tool — Jekyll's layout field controls which template wraps the page, Astro's content collections validate frontmatter against a schema you define — but the wrapping syntax is identical across all of them.
Obsidian notes
Obsidian calls this same block "Properties" in its UI but stores it as plain YAML frontmatter in the underlying .md file. Per Obsidian's own documentation, "properties are stored in YAML format at the top of the file," with built-in properties like tags, aliases, and cssclasses, plus whatever custom fields a note needs. You can view the raw YAML at any time by switching a note to Source mode.
AI agent skill and command files
Frontmatter has recently picked up a newer use case: configuring AI coding agents. Claude Code's skill files, for example, are Markdown files named SKILL.md with a YAML frontmatter block at the top — Anthropic's documentation describes the two required fields as name and description, which the agent scans to decide when to load the full skill. It's the same triple-dash, key-value pattern, just read by a different consumer.
Blog platforms and CMSs
Markdown-based blogging tools generally follow the same idea: a YAML header sets the post's title, description, slug, and publish status, and the CLI or API that ingests the file reads those fields instead of asking you to fill out a separate web form. Blogizi's Markdown format works this way — more on that at the end.
Common YAML Frontmatter Fields for a Blog Post
Exact field names vary by platform, but most Markdown-based blogging tools expect some version of the following:
title— the post's headline, usually rendered in the page's<title>tag and at the top of the post.description— a one- or two-sentence summary, often reused as the meta description for search results.date— the publish date, typically inYYYY-MM-DDformat.slug— the URL segment for the post (e.g.,my-post-slugforexample.com/my-post-slug).tagsorcategories— a list used for archive pages and internal linking.statusorpublished— whether the post is a draft or live.
A minimal, working example for a blog post looks like this:
---
title: "How I Migrated My Blog to Markdown"
description: "Why I moved off a CMS and what changed."
date: 2026-08-12
tags:
- migration
- markdown
status: draft
---
Common Mistakes and How to Fix Them
Most frontmatter failures come down to a handful of repeat offenders:
Missing or mismatched delimiters. If the closing --- is missing, or there's a blank line before the opening one, the parser either fails outright or treats your entire file — metadata and all — as page content.
Unquoted strings with special characters. A title like Docker vs. Podman: What's the Difference? contains a colon, which YAML will try to interpret as a new key. Wrap the value in quotes whenever it contains a colon, starts with #, *, &, or %, or looks like a number or boolean but should be text (a version string like 1.0, for example).
Tabs instead of spaces. YAML's indentation rules do not allow tabs. Most editors insert spaces by default, but if yours doesn't, mixed tabs and spaces will produce a parse error that can be hard to spot visually.
Inconsistent indentation. Once you pick an indentation width for nested keys or lists, use it everywhere in that block. A stray extra space is enough to break parsing.
Duplicate keys. YAML doesn't warn you if you accidentally define the same key twice in one block — most parsers silently keep the last value and discard the first, which can produce confusing bugs.
Wrong date format. Unquoted dates like 2026-08-12 are parsed as YAML's native date type in most implementations. If a tool expects a plain string instead, wrap it in quotes: date: "2026-08-12".
YAML Frontmatter vs. JSON Frontmatter
YAML is by far the most common frontmatter format, but it isn't the only one. Some tools accept a JSON block instead — Obsidian, for instance, documents JSON as a supported alternative, noting that it's read, interpreted, and saved back to YAML regardless of which format you typed. A few static site generators also support TOML, delimited with +++ instead of ---. Unless a specific tool's documentation says otherwise, YAML between triple dashes is the safest default — it's the format the widest range of Markdown tooling expects out of the box.
Writing Frontmatter Without Doing It by Hand
Frontmatter is simple once you know the syntax, but it's still easy to typo a field name, forget a required key, or mismatch quoting when you're writing it from scratch for the tenth post in a row. If you'd rather not hand-write the YAML block every time, Blogizi has a free Markdown Frontmatter Generator that outputs a correctly formatted block — title, description, keyword, slug, date, and status — ready to paste at the top of a file, no account required.
That same field structure is what Blogizi's CLI and Obsidian plugin read when you're ready to publish: write a Markdown file with frontmatter, then push it to a hosted blog as a draft or a live post with one command, without wiring up a CMS. If you're already writing in Markdown, it's worth a look — and if you're not ready for that, the frontmatter generator works on its own regardless of where you end up publishing.