YAML Frontmatter Explained: The Secret Header Powering Static Sites

If you've ever looked at a markdown file for a blog post or documentation page and seen a block of text between --- lines at the top, that's YAML frontmatter. It's a simple but powerful convention that turns a plain text file into a structured content object.

What Does It Look Like?

Here's a real example from this very blog:

---
title: "YAML Frontmatter Explained"
slug: "yaml-frontmatter-explained"
date: 2026-03-19
category: "Automation & Tools"
description: "YAML frontmatter is the metadata block..."
tags: ["yaml", "markdown", "static-sites"]
featured: false
---

Your markdown content starts here...

The --- fences at the top and bottom mark the boundary of the frontmatter block. Everything between them is parsed as YAML — a human-readable data format. Everything after the closing --- is your regular markdown content.

Why Use Frontmatter?

Markdown is great for writing content, but it has no built-in concept of metadata. It doesn't know what your post is called, when it was published, or what category it belongs to. Frontmatter solves this by giving each file a structured header that code can parse.

This means a single .md file contains both:

• Metadata (title, date, tags, author, etc.) — machine-readable
• Content (the actual article) — human-readable

No database needed. No CMS admin panel. The file is the content and its metadata, all in one place.

How It Works Under the Hood

When a static site generator or web framework reads a markdown file with frontmatter, it does two things:

1. Splits the file at the --- markers to separate the YAML header from the markdown body
2. Parses the YAML into a structured object (a dictionary, class, or hash map depending on the language)

In C# with the YamlDotNet library, parsing looks something like this:

var content = File.ReadAllText("my-post.md");
var endIndex = content.IndexOf("---", 3);  // Find closing ---
var yaml = content[3..endIndex].Trim();     // Extract YAML
var markdown = content[(endIndex + 3)..];   // Extract content

var metadata = deserializer.Deserialize<PostMetadata>(yaml);
var html = Markdown.ToHtml(markdown);

In Python, JavaScript, Go, or Ruby — every language has libraries that do the same thing. The convention is universal.

What Can You Put in Frontmatter?

Anything that's valid YAML. Common fields include:

You can define whatever fields make sense for your use case. There's no fixed schema — it's your data model.

YAML Basics You Need to Know

If you're new to YAML, here are the essentials:

Strings — quotes are optional unless the value contains special characters:

title: My Post Title
title: "My Post: With a Colon"

Dates — use ISO 8601 format:

date: 2026-03-19

Booleans:

featured: true
draft: false

Lists — use square brackets or dashes:

tags: ["aws", "cloud", "devops"]

# or
tags:
  - aws
  - cloud
  - devops

Indentation matters — YAML uses spaces (never tabs) for nesting. Two spaces is the convention.

Who Uses Frontmatter?

Nearly every modern static site tool relies on frontmatter:

• Jekyll (GitHub Pages) — the tool that popularized the convention
• Hugo — supports YAML, TOML, and JSON frontmatter
• Gatsby — uses frontmatter with GraphQL queries
• Next.js — with MDX or markdown plugins
• Astro — first-class frontmatter support
• Custom apps — like this site, which is an ASP.NET Core app that reads markdown files at startup

If you're building any kind of content-driven application and want to avoid a database, frontmatter is probably your answer.

The Tradeoffs

Advantages:

• Files are self-contained — metadata and content live together
• Human-readable and editable in any text editor
• Version-controllable with Git — full history of every change
• No database to manage, back up, or migrate
• Works with any programming language

Limitations:

• No real-time querying — you read all files into memory (fine for hundreds of posts, less ideal for millions)
• No relational data — you can't JOIN between posts the way you would with a database
• Editing requires a text editor and deployment — there's no admin UI (unless you build one)

For a personal blog or documentation site with up to a few thousand pages, frontmatter is the sweet spot of simplicity and power.

This site runs on markdown files with YAML frontmatter, rendered by ASP.NET Core. Read about how I migrated from WordPress to this setup.