YAML front matter is a block of key: value lines between two lines of three dashes at the very top of a Markdown file, holding details about the file, such as its title and date, rather than its text.
What it looks like
---
title: Issue 42
date: 2026-11-10
status: draft
tags:
- newsletter
- agents
---
# This week
The draft starts here.
Each line between the dashes is a key, a colon and a space, then the value. A list goes on the lines below its key, one - item per line.
Rules that trip people up
- It must come first. The opening
---is the very first line of the file, with nothing above it, not even a blank line. - Indent with spaces. YAML doesn't allow tabs for indentation.
- Quote a value with a colon and a space in it.
title: "Part 1: The setup"works; without the quotes the second colon breaks the line.
What reads it
Site generators such as Jekyll read front matter to set a page's title, date and layout, and don't print it as text. Agents such as Claude Code read it with the rest of the file, so a line like status: draft is something you can point an agent at: "list the issues still in draft".
In Flywrite
In Rendered view, front matter at the top of a file shows as a card of fields: each key with its value in a field you can edit. Lists and other values that run over several lines show as plain text in the card. Click a key, or move the cursor into the block, to edit the YAML itself. Source view shows the block as typed, and the file stays plain Markdown either way.
Questions
Is front matter YAML or Markdown?
Both, in one file. The block at the top is YAML, and everything after the closing --- line is Markdown.
What happens in an app that doesn't know front matter?
It shows the block as ordinary text. In plain Markdown, the opening --- line is a horizontal rule, so the block reads as a rule followed by a paragraph or heading.
- Jekyll docs: Front Matter. Checked .
- YAML 1.2.2 specification. Checked .
- GitHub Flavored Markdown Spec. Checked .