YAML frontmatter in Markdown

Frontmatter is a block of metadata at the very top of a Markdown file, fenced between two lines of three dashes, holding key: value pairs. It's usually written in YAML and commonly carries a title, a date, and a list of tags. The rest of the document follows below it.

The body of a Markdown file is the writing. Frontmatter is the data about the writing. Things a person reading the page doesn't need in the text but a program does: when it was published, who wrote it, whether it's still a draft.

Static site generators read it to build pages. Note apps read it to sort and filter. You write it once at the top, and tools take it from there.

The basic shape

Frontmatter goes first in the file. Nothing before it, not even a blank line. You open with a line of three dashes, write your pairs, and close with another line of three dashes.

---
title: Trip notes
date: 2026-06-28
---

# Trip notes

The writing starts here.

The block between the two --- lines is YAML. Each line is a key, a colon, a space, then a value. The two fences mark where the metadata stops and the document begins.

Keys and values

A key names the field. The value is what you set it to. Keep the space after the colon. That space is part of the syntax, not just tidiness.

---
title: Q3 planning
author: Dana Okafor
status: draft
---

Values are plain text by default, so you don't need quotes around an ordinary string. You only need quotes when the value contains a character YAML would otherwise read as syntax, like a leading colon or a #.

---
title: "Notes: week one"
---

Here the quotes keep the colon inside the value instead of YAML treating it as a second key.

Dates, numbers, and true/false

YAML reads some values as types, not just text. A date in YYYY-MM-DD form is a date. A bare number is a number. true and false are booleans.

---
date: 2026-06-28
priority: 2
published: false
---

This is why a draft flag works. A tool can check published: false and skip the file. You wrote three plain lines. The program reads a date, a number, and a yes/no.

Lists and tags

A common need is more than one value for a field, like several tags. YAML gives you two ways to write a list.

The inline form puts the items in square brackets on one line:

---
tags: [markdown, mac, writing]
---

The block form puts each item on its own line, indented, behind a dash:

---
tags:
  - markdown
  - mac
  - writing
---

Both mean the same list. Pick the inline form for a short set, the block form when the list is long or you want it easy to scan. The indentation in the block form matters: two spaces, consistently.

In Unmarked

Unmarked reads the YAML block at the top of the file and renders it as a properties panel above your document, instead of dumping the raw key: value lines into the page. The source file on disk stays exactly as you typed it.