---
title: YAML front matter
nav: YAML front matter
order: 3
description: That block of metadata fenced by --- at the top of a file. Here it renders as a card instead of being mangled by the parser.
updated: 2026-08-12
---

## What it is

Static site generators (Hugo, Jekyll, Astro) and note apps (Obsidian) share a convention:
a file may begin with a block of YAML fenced by `---`, holding metadata such as title, date, and tags.

```
---
title: Post title
date: 2026-08-12
tags: [markdown, editor]
draft: false
---

The body starts here.
```

There are only two rules, and neither can be bent:

1. The opening `---` must be on the **very first line** — not even a blank line before it.
2. Another line of `---` closes the block.

## Why it needs special handling

Plain Markdown knows nothing about front matter. Feed the block above to an ordinary parser and you get:
the first `---` becomes a horizontal rule, `title: Post title` becomes body text, and the closing `---`
becomes another rule — in other words, a mess.

This editor lifts the front matter out first and renders it as a card labeled **YAML Front Matter**;
only the remaining body goes to the Markdown parser. So the preview shows:

> **YAML Front Matter**
> A boxed block that displays your fields exactly as you wrote them.

The first heading of your body stays the first heading of your body.

## What the editor does not do

- **It does not validate the YAML.** Broken indentation or a missing colon still shows up in the card; nothing errors. Validation is your generator's job.
- **It does not interpret the fields.** `title` does not become the preview's heading, and `draft: true` does not grey the document out. The editor's job is to preserve the metadata and show it.
- **It does not add front matter for you.** New files start empty.

That is deliberate: the editor's contract is *don't break your file*. What the fields mean is the generator's business.

## Try it

This page is itself an example. Download it as `.md` with the link below, open it in the editor, and the
`title` and `order` lines at the top appear as a card.