If you've opened a markdown file and seen something like this at the top, you've encountered frontmatter:

---
title: Blog Post Title
date: 2026-02-21
author: Ryan McDonald
tags: [markdown, tutorial]
---

The dashes and the fields between them are frontmatter — metadata about the document. Understanding what frontmatter is, why it exists, and how it works will help you use markdown more effectively in blogs, documentation, and note-taking tools.

What Is Frontmatter?

Frontmatter is structured metadata at the top of a markdown file. It's separated from the document content by lines of three dashes (---).

The metadata is written in YAML, a human-readable data format. Think of it as a dictionary of information about the document: who wrote it, when it was published, what category it belongs to, what tags apply to it, and so on.

Everything below the closing --- is the actual markdown content.

---
title: "My Document"
date: 2026-02-21
author: "Jane Doe"
---

# Content starts here

This is the body of the document in markdown.

Why Does Frontmatter Exist?

Markdown is designed to be a format for writing text with simple formatting. It doesn't have a built-in way to store metadata like publication date, author, or tags. Early markdown users needed a way to attach this information to documents, especially in blogs and documentation systems.

The solution was to add a structured metadata block at the top of the file. This allows the file to be:

Self-contained — All the information (metadata + content) lives in one file
Parseable — Tools can extract the metadata without parsing the entire markdown content
Human-readable — The YAML format is simple enough to edit by hand
Version-controllable — It's plain text, so it works perfectly with Git

YAML Syntax Basics

YAML (YAML Ain't Markup Language) is a data format that's designed to be readable by humans. Here are the basic types:

Strings

title: "My Blog Post"
author: Jane Doe
description: "This is a longer description."

Strings don't need quotes unless they contain special characters or span multiple lines.

Lists

tags: [markdown, blog, tutorial]

Or multi-line:

tags:
  - markdown
  - blog
  - tutorial

Numbers

date: 2026-02-21
views: 1500
rating: 4.5

Booleans

published: true
featured: false

Nested Objects

author:
  name: Jane Doe
  email: jane@example.com
  bio: "Writer and developer"

Common Frontmatter Fields

Different tools use different field names, but here are the standard ones you'll see:

Field	Purpose	Example
`title`	Document title	`title: "Blog Post Title"`
`date`	Publication or creation date	`date: 2026-02-21`
`updated`	Last modified date	`updated: 2026-02-22`
`author`	Author name	`author: Ryan McDonald`
`description`	Short summary (for search engines)	`description: "Why markdown matters"`
`tags`	Categories or labels	`tags: [markdown, tutorial]`
`slug`	URL-friendly name	`slug: markdown-guide`
`draft`	Is this a draft?	`draft: false`
`featured`	Highlight this post?	`featured: true`
`image`	Hero image or thumbnail	`image: /images/hero.png`

Where Is Frontmatter Used?

Static Site Generators

Tools like Jekyll, Hugo, Gatsby, and Next.js use frontmatter to extract metadata about pages:

---
title: "Getting Started with React"
date: 2026-01-15
category: "Web Development"
---

# Content here

The site generator reads the frontmatter and uses it to:

Set the HTML page title and meta tags
Sort and filter posts
Generate site navigation
Create RSS feeds

Blogging Platforms

Obsidian, Bear, and other note-taking apps use frontmatter to store metadata about notes:

---
created: 2026-02-21
modified: 2026-02-23
tags: [project-alpha, important]
---

This allows the app to organize, search, and filter notes based on metadata.

Documentation Tools

Tools like MkDocs and ReadTheDocs use frontmatter to configure how pages are rendered:

---
title: "API Reference"
nav_order: 5
---

Git-based CMS

Netlify CMS, Forestry, and other headless CMS systems store content as markdown files with frontmatter and allow non-technical users to edit them through a form interface.

Frontmatter in This Website

This blog post, and every blog post on this website, uses frontmatter:

---
title: 'Markdown Frontmatter and YAML: Metadata Headers Explained'
date: '2026-02-21'
description: >
  What markdown frontmatter (YAML headers) is, how it works, and why it exists.
author: Ryan McDonald
tags: [markdown, yaml, frontmatter, metadata, technical]
---

This metadata is:

Extracted by Next.js to generate the page title, meta descriptions, and Open Graph tags
Used for sorting to display posts in reverse chronological order
Used for tagging to group related posts
Used for author attribution to credit the writer

Without frontmatter, this metadata would have to live somewhere else — in a database, a separate config file, or hard-coded in code. By keeping it in the file itself, the markdown file is self-contained and portable.

YAML Best Practices

1. Use Quotes for Strings with Special Characters

title: "This: A Title with a Colon"
description: "Use quotes if there are special chars"

2. Format Dates Consistently

date: 2026-02-21      # ISO 8601 format is standard
# OR
date: "Feb 21, 2026"

3. Use Lists for Multiple Values

tags: [python, web, tutorial]
# NOT
tags: python, web, tutorial  # This will break

4. Use `>` for Multi-line Strings

description: >
  This is a long description that spans
  multiple lines. The `>` character joins them
  into a single line with spaces between.

5. Validate Your YAML

If your frontmatter breaks, your site won't build. Use a YAML validator like yamllint.com to check your syntax.

Frontmatter vs. Inline Metadata

Some tools allow metadata inline in the markdown content instead of at the top. For example, some apps extract title from the first # Heading and date from the file's modification timestamp.

Frontmatter is more explicit and reliable:

Explicit: The metadata is clearly defined at the top, not inferred
Flexible: You can have metadata that doesn't appear in the document (like draft: true)
Reliable: Tools don't have to guess or make assumptions

Converting Between Formats

If you're moving markdown between tools (from a blog to Obsidian, from Hugo to Jekyll), frontmatter usually survives because it's plain text. However, field names might differ, so you may need to rename fields to match the new tool's conventions.

Learning More

For a guide to writing markdown content itself (separate from metadata), see How to Write Markdown: A Beginner's Guide.

For a reference of all markdown syntax, including tables and extended features, see Markdown Quick Reference.

Download OpenMark → — $9.99, one-time, native macOS. View markdown files with full support for frontmatter, YAML headers, and all markdown formatting. Perfect for developers, writers, and content creators.