What is YAML front matter?

Sometimes a document needs information about the document itself: a title, tags, a date, or a publishing status.

Some apps and publishing tools store that information in a block at the top of the file. One common form is YAML front matter.

---
title: "A useful note"
tags:
  - writing
  - reference
status: draft
---

The body of the document follows the closing delimiter.

What the fields mean

In this example, title holds a title, tags holds a list, and status holds a value. The tool reading the file decides whether those fields mean anything to it.

There is no universal set of Markdown metadata fields. A field that controls publishing in one tool might do nothing in another.

Keep the first example small

Start with the fields your tool documents. Quote string values when they contain punctuation or could be interpreted as another type. Use consistent spaces for indentation; YAML indentation does not use tabs.

---
title: "Meeting: launch review"
status: "draft"
---

Don’t add metadata because the file looks more complete with it. Add a field when something uses it or when it helps you organize the work.

Before you move the file

Check whether the receiving tool recognizes front matter. Otherwise, the block may remain visible as text or be interpreted as ordinary Markdown.

Keep a copy before changing a large set of metadata. Test one file first.

Next: Understand portability.

Example: a title that contains a colon

Quote the whole string so the punctuation stays part of the value.

---
title: "Meeting: launch review"
status: "draft"
---

Example: tags as a list

Indent each item beneath the field it belongs to.

---
title: "Reference notes"
tags:
  - writing
  - markdown
---

Example: metadata followed by the body

This is a complete file example for a tool that recognizes YAML front matter. The visible heading belongs in the body. A title field does not automatically create that heading in every tool.

---
title: "Project brief"
date: "2026-10-03"
status: "draft"
---

# Project brief

## What we're making

A short guide for first-time readers.

Common mistakes to check

• Tabs in indentation: use spaces for YAML indentation.
• A missing closing delimiter: the tool may fail to identify where the body begins.
• An unquoted value that looks like another type: quote dates and other values when you intend to store text, then check the tool’s expected field type.
• An unknown field: valid YAML can still contain a field the app doesn’t use.

For a concrete publishing example, Jekyll’s front matter documentation explains how that tool interprets metadata. Its fields are not a universal Markdown contract.