Skimmark / Blog

What is front matter in Markdown?

Bobby Huang ·

Front matter is a small block of data at the very top of a Markdown file that describes the file instead of being part of its text. It sits between two lines of three dashes. Most front matter is written in YAML, a plain format of key and value pairs. Tools that read front matter turn these fields into data. Tools that don't read it show the block as plain text at the top of the page.

Key takeaways

  • Front matter holds facts about the file, not the content of it.
  • It must be the first thing in the file, between two lines of exactly three dashes.
  • The content must be valid YAML. One bad indent or an unquoted colon can break the whole block.
  • Keys are case-sensitive. Status and status are two different fields.

Front matter is a small block of data at the very top of a Markdown file that describes the file instead of being part of its text.

It sits between two lines of three dashes. Most front matter is written in YAML, a plain format of key: value pairs.

What it looks like

---
title: Q3 vendor review
status: draft
owner: Jane Doe
date: 2026-01-15
tags: [vendors, review]
---

# Q3 vendor review

The body of the note starts here.

Everything between the dashes is front matter. Everything after the closing dashes is the document.

What front matter is for

Front matter holds facts about the file, not the content of it. Common uses:

  • Titles and dates. A site builder can use them for page titles and sort order.
  • Status. A field like status: draft tells a person or a script where the file stands.
  • Ownership. owner: Jane Doe says who is responsible.
  • Tags. A list of tags lets tools group related files.

Tools that read front matter turn these fields into data. Tools that don't read it show the block as plain text at the top of the page.

Why agent-written files often have it

AI agents that write Markdown often add a header so other tools can track the file. A report from an agent working for Doe Holdings might carry status, date, and owner on every run. That header changes as the agent rewrites the file, so it is worth reading, not skipping.

Front matter rules in short

  • It must be the first thing in the file. Nothing, not even a blank line, goes before the opening dashes.
  • The opening and closing lines are exactly three dashes.
  • The content must be valid YAML. One bad indent or an unquoted colon can break the whole block.
  • Keys are case-sensitive. Status and status are two different fields.

When one of these rules is broken, many tools give up and show the raw text. See Common YAML front matter errors and how to fix them for the usual causes and fixes.

Related terms

  • YAML: the data format most front matter uses.
  • TOML front matter: a variant fenced with +++ instead of ---.
  • Metadata: the general term for data about a file. Front matter is one way to store it inside the file itself.

Reading front matter without the raw YAML

Raw YAML is easy to misread when a file has many fields. Skimmark, a Markdown reader in development, has a Frontmatter Table planned for v1: the YAML header shown as key/value rows above the rendered page.

Go deeper

For a full walk-through of fields, quoting, and lists, read the pillar guide: YAML front matter in Markdown: a practical guide.

To see what Skimmark is and follow along, visit skimmark.com.

View as Markdown