Markdown Frontmatter: A Complete Guide to YAML Metadata

If you have ever opened a Markdown file from a blog or documentation site and seen a block of key: value lines fenced by three dashes at the very top, you have met frontmatter. It looks like part of the document, but it never shows up in the rendered page. Instead it carries metadata that tools use to build titles, dates, navigation, and more.

Quick Answer: Markdown frontmatter is a block of YAML metadata at the top of a Markdown file, wrapped between two lines of three dashes. It stores structured data like title, date, and tags that static site generators and content tools read to control how the page is built, without that data appearing in the visible content.

This guide explains the syntax, the most useful fields, common data types, and the mistakes that break a build.

What Does Frontmatter Look Like?

Frontmatter sits at the very top of the file, before any content, and is delimited by three dashes on their own lines:

---
title: "Getting Started With Markdown"
date: 2026-05-31
author: "Jordan Lee"
tags: ["markdown", "tutorial"]
draft: false
---

Your article content begins here, after the closing dashes.

The block between the dashes is YAML, a human readable format for structured data. Everything inside it is metadata. Everything after the closing dashes is your normal Markdown.

It must be the first thing in the file. Even a single blank line above the opening dashes can stop a tool from recognizing it.

Which Fields Should You Include?

Field names are not fixed by Markdown itself. Each tool defines what it reads. That said, a common set shows up almost everywhere:

• title the page or post title, often used for the h1 and the browser tab
• description a short summary used for meta tags and previews
• date the publish date, used for sorting and display
• tags a list of topics for filtering and related content
• slug an explicit URL segment when you do not want it derived from the filename
• draft a flag to keep unfinished work out of production

A blog post might use all of these. A documentation page might only need a title and an order number for sidebar placement.

What Data Types Does YAML Support?

YAML covers the types you need for metadata:

title: "A string in quotes"
readingTime: 6
published: true
tags:
  - markdown
  - guide
author:
  name: "Sam Rivera"
  url: "https://example.com"

This shows the main shapes:

• Strings plain text, quoted when they contain special characters like colons
• Numbers written without quotes
• Booleans true or false
• Lists either inline with brackets or as indented dashes
• Nested objects indented key: value pairs under a parent

Indentation is meaningful in YAML, much like it is in Python. Two spaces per level is the safe convention, and tabs are not allowed.

How Do Tools Use Frontmatter?

A static site generator or content library reads the frontmatter, separates it from the body, and hands both to your templates. The classic pairing in the JavaScript world is a library that parses the YAML block into an object while returning the Markdown body separately. Your code then uses data.title, data.date, and the rendered body to build the page.

This is exactly how a Markdown driven blog typically works. The list page sorts posts by date, the article page renders the body, and the meta tags come from title and description. If you are building such a system, our guide on Markdown for blogging covers the bigger picture.

What Are the Most Common Frontmatter Mistakes?

A few errors break builds more than any others:

• A blank line before the opening dashes. Frontmatter must be the very first content.
• Unquoted strings with colons. A title like Markdown: A Primer needs quotes, or YAML reads the colon as a key separator.
• Mixed tabs and spaces. Stick to spaces for indentation.
• Inconsistent date formats. Match whatever format your tool expects, commonly YYYY-MM-DD.
• Forgetting the closing dashes. Without them the parser swallows your whole document as metadata.

When a build fails on a content file, frontmatter is the first place to look. Render the file in a tool like edtr.md to confirm the body looks right, then check the metadata block line by line.

Put It Into Practice

Frontmatter is the quiet engine behind most Markdown publishing. Get the YAML right and your tools handle titles, dates, tags, and navigation for you. Open a file in edtr.md, add a frontmatter block with a title and a few tags, and you have the foundation that powers blogs, docs, and static sites everywhere.