# YAML front matter

YAML front matter is a block of key and value lines between two --- lines at the top of a Markdown file. What it holds, how to write it and what reads it.

**Definition:** 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

```markdown
---
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.

## Sources

1. [Jekyll docs: Front Matter](https://jekyllrb.com/docs/front-matter/), checked 2026-11-10
2. [YAML 1.2.2 specification](https://yaml.org/spec/1.2.2/), checked 2026-11-10
3. [GitHub Flavored Markdown Spec](https://github.github.com/gfm/), checked 2026-11-10

---

This is the Markdown copy of https://flywrite.app/glossary/yaml-front-matter.
