---
title: YAML Frontmatter Explained: The Secret Header Powering Static Sites
slug: yaml-frontmatter-explained
date: 2026-03-19
category: Automation & Tools
description: YAML frontmatter is the metadata block at the top of markdown files that powers blogs, documentation sites, and static site generators. Here's what it is and how to use it.
---

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:

```yaml
---
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:

```csharp
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:

| Field | Purpose | Example |
|-------|---------|---------|
| `title` | Post title | `"How to Deploy to AWS"` |
| `date` | Publication date | `2026-03-19` |
| `slug` | URL-friendly identifier | `"deploy-to-aws"` |
| `description` | SEO meta description | `"A step-by-step guide..."` |
| `category` | Content grouping | `"AWS"` |
| `tags` | Keyword labels | `["aws", "deploy", "ci-cd"]` |
| `author` | Who wrote it | `"Nat Thompson"` |
| `featured` | Highlight on homepage | `true` |
| `draft` | Hide from listing | `true` |
| `image` | Hero/thumbnail image | `"/images/post-hero.jpg"` |

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:

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

**Dates** — use ISO 8601 format:

```yaml
date: 2026-03-19
```

**Booleans**:

```yaml
featured: true
draft: false
```

**Lists** — use square brackets or dashes:

```yaml
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](/blog/what-is-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](/blog/replacing-wordpress-with-dotnet-razor-pages) to this setup.*