The Three Dashes at the Top of Your Note: How YAML Frontmatter Adds Structure Without a Database

YAML frontmatter is a block of key-value lines between two --- fences at the very top of a Markdown file. It holds the note's metadata — its date, its tags, its status — inside the note itself. Any tool can read it. No tool can take it away, because it is just text in a file you own.

You have seen it. Open almost any .md file from a static site or a note app and the first thing you meet is a fence of three dashes, a short stack of key: value lines, then another fence. Most people scroll past it.

It is the most useful four characters in your notes, and almost nobody explains what they are for. This post does: where the convention came from, what one note looks like when four tools read it, and the payoff that arrives the moment your structure lives in plain text instead of a hidden database row.

What is YAML frontmatter?

YAML frontmatter is structured metadata, written in YAML, placed between a pair of --- fences at the top of a Markdown file. The fences mark where the data ends and the prose begins. The keys inside — title, date, tags — let humans and software sort, filter, and find the note without reading its body.

YAML is the serialization format doing the work. Its own home page calls it "a human-friendly data serialization language for all programming languages." ¹ That phrase is the whole argument for putting metadata in text rather than a database: the structure stays readable by a person and parseable by a machine. A note's date is not buried in a binary record. It is a line that says date: 2026-06-17, sitting where you can see it.

Here is the minimal shape:

---
title: Quarterly review notes
date: 2026-06-17
tags: [work, planning]
status: draft
---

The body of the note starts here, in ordinary Markdown.

The block above is the metadata. Everything below the closing --- is the note. That separation — data on top, prose underneath — is the entire idea.

Where the three dashes came from

The triple-dash convention was popularized by Jekyll, the static-site generator released in 2008. Jekyll's rule is exact: "The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines." ² A valid block changes how the file is handled.

A file carrying that block is treated differently from a plain one — "Any file that contains a YAML front matter block will be processed by Jekyll as a special file." ³

That second rule is the lineage in one sentence. The presence of a valid --- block is a signal. It flips the file from "render this as-is" to "read these keys, then render." Other tools inherited the pattern. Hugo, another popular site generator, supports the same idea and detects which format you used by the fences: "Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content." ⁴

YAML became the default, not the only choice. Hugo accepts three serialization formats — YAML between ---, TOML between +++, and JSON inside { } braces. ⁴ Eleventy, a third generator, settles the question the same way most tools do: "By default, yaml is used when a front matter syntax is not explicitly specified." ⁵ Three independent tools, three teams, one inherited convention. That is why frontmatter is worth learning once.

One note, four readers

The reason to write frontmatter by hand is that the same block is read by tools that never agreed to cooperate. Write the metadata once in plain YAML — a static-site generator, a note app, a folder-wide search, and an uninstalled future tool all read the identical lines. The structure lives in the file, not one program.

Take this single note and hand it to four readers:

---
title: Reading notes — Local-First Software
date: 2026-06-17
tags: [reading, local-first, ownership]
status: active
aliases: [Ink and Switch paper]
---

Files outlast the apps that made them.

• Jekyll sees a special file with page variables it can publish. ³
• Hugo reads the same keys as metadata that "Describes the content," "Augments the content," and "Establishes relationships with other content." ⁶
• Obsidian displays the block as Properties — "Properties are stored in YAML format at the top of the file. YAML is a popular format that is easy for both humans and computers to read." ⁷ Its property types cover Text, List, Number, Checkbox, Date, and Date & time, plus Tags. ⁸ Toggle the editor to Source mode and the friendly form dissolves back into the raw fence: the Source view "displays properties in plain text YAML format." ⁹ The UI is sugar; the file is the truth.
• A plain text search (grep, your editor's find, a script) reads it as exactly what it is — lines of text it can match.

flowchart TD
    F["note.md<br/>--- YAML block ---"]
    F --> J["Static-site<br/>generator"]
    F --> O["Note app<br/>(Properties)"]
    F --> G["Plain-text<br/>search / grep"]
    F --> X["Future tool<br/>not built yet"]

Figure: one Markdown file with a YAML frontmatter block, read independently by four tools. The file is the single source of truth; each reader interprets the same --- block on its own — a static-site generator turns the keys into page variables, a note app renders them as a properties form, a text search matches them as lines, and a tool that does not exist yet can read them the day it ships. Nothing is locked to one program.

This is the structural fact that makes frontmatter durable. The metadata does not live in a database that belongs to one application. It lives in the file, and the file is portable.

How to add frontmatter to a note in five minutes

To add frontmatter, put your cursor at the very first line of the file, type --- and press enter, write one key: value per line, then close with another ---. Save. That is the whole mechanic. The block must be the first thing in the file, and every key sits at the left margin with no leading spaces.

A working sequence:

1. Go to line 1. Nothing may come before the opening fence — not a heading, not a blank line.
2. Type --- and press enter.
3. Add keys, one per line: title: My note, then date: 2026-06-17.
4. For a list, use bracket form tags: [work, ideas] or a dashed block on the next lines.
5. Close the block with a second --- on its own line.
6. Leave a blank line, then write the note.

The five keys that travel well across tools are title, date, tags, aliases, and status. None of them is mandatory and none is standardized — they are a de-facto vocabulary, convention rather than law. Pick the few you will actually filter on — and ignore the rest.

The payoff: grep it, query it, never lose it

Because frontmatter is plain text, the structure is immediately searchable and queryable with ordinary tools — no export, no database, no app required. You can grep every note tagged reading. You can list every note whose status is active. You can sort by date. The metadata you typed by hand becomes a small, honest index that any program can read.

Find every note still in draft, across an entire folder, with one line:

grep -rl "status: draft" .

That command needs nothing but the files. The same status: key that a note app shows as a tidy dropdown is, underneath, a string a shell can match. This is where frontmatter meets the query layer: structured Markdown metadata is exactly what turns a folder of notes into a database without a silo — frontmatter is the input format those queries read.

The tags: list you write here is also where tags physically live when you choose tags over folders, and it pairs with the filename as the one piece of metadata that survives with no app at all. The filename is the cheapest index; frontmatter is the richer one inside the file.

Honest caveats: what frontmatter is not, and where YAML bites

Frontmatter is not part of Markdown, and that is worth saying plainly. The CommonMark specification, the formal definition of standard Markdown (version 0.31.2, dated 2024-01-28), contains zero occurrences of "front matter," "frontmatter," "YAML," or "metadata." ¹⁰ It is a widely adopted convention layered on top, not a guaranteed feature.

Frontmatter sits on Markdown the same way wiki-links are a convention and not core Markdown either. A bare-bones renderer that does not know the convention will simply print the --- block as visible text.

YAML also has a famous trap worth one rule. Under YAML 1.1, several bare words are read as booleans, not strings — yes, no, on, off, true, false, in many capitalizations. The 1.1 type specification lists them by regular expression and gives the example answer: NO parsing as the boolean false. ¹¹ This is the "Norway problem": write country: NO for Norway and a 1.1 parser turns it into false.

YAML 1.2 narrowed booleans to true/false only, ¹² but widely used parsers still default to 1.1 behavior, so the gotcha is live in real files. The fix is one habit: quote any string value that could be mistaken for a boolean — answer: "no", country: "NO". YAML is also whitespace-sensitive, so keep keys flush-left and indent list items consistently.

How this works in a plain-Markdown note app

In an app built on plain Markdown, like MNMNOTE, frontmatter is not a feature bolted on; it is just the top of your file. You type the --- block, the app reads the keys, and the same metadata stays in the file when you copy it or open it elsewhere. The structure is yours because the file is yours.

The villain in this story was never a particular app. It is metadata trapped in a proprietary database row — a date or a tag you can see in one program and nowhere else, that vanishes the day the program does. Frontmatter is the antidote.

Steph Ango, Obsidian's CEO, put the principle plainly: "File over app is a philosophy: if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read." ¹³ A --- block is that idea made concrete.

Frequently asked questions

The questions below cover what frontmatter is, how to write it, and the two honest caveats worth knowing before you commit to it: that it is a convention rather than core Markdown, and that YAML quietly turns a few bare words into booleans. Each answer points back to a primary source.

What is YAML frontmatter?

YAML frontmatter is a block of key-value metadata, written in YAML, placed between two --- fences at the very top of a Markdown file. It records details like the note's title, date, tags, and status inside the file itself, so any tool — and any reader — can sort and filter notes without opening each one.

What do the three dashes at the top of a Markdown file mean?

The three dashes (---) are a fence. An opening --- and a closing --- delimit a frontmatter block. Everything between them is parsed as YAML metadata; everything after the closing fence is the note's body. Jekyll established the rule that this block must be the first thing in the file. ²

How do I add metadata to a Markdown note?

Put your cursor on line 1, type --- and press enter, add one key: value per line (for example date: 2026-06-17 and tags: [work, ideas]), then close with a second ---. Save the file. The block must come before any heading or text.

Is frontmatter part of Markdown?

No. The CommonMark specification (v0.31.2, 2024-01-28) has zero mentions of front matter, YAML, or metadata. ¹⁰ Frontmatter is a convention adopted by many tools — Jekyll, Hugo, Eleventy, Obsidian — layered on top of Markdown, not part of its core syntax.

Why does YAML turn NO into false?

Under YAML 1.1, bare words such as yes, no, on, and off are implicitly typed as booleans. ¹¹ So country: NO can become false. YAML 1.2 restricts booleans to true/false, ¹² but many parsers still default to 1.1. Quote the value — country: "NO" — to keep it a string.

Do all tools read the same frontmatter keys?

The fence and YAML format are shared, but the vocabulary is not standardized. title, date, and tags are de-facto common across tools; beyond those, each tool reads the keys it cares about and ignores the rest. Decide which keys you will filter on, and keep them consistent across your notes.

Can I use TOML or JSON instead of YAML?

In some tools, yes. Hugo, for instance, accepts YAML between ---, TOML between +++, and JSON inside braces, detecting the format by the delimiters. ⁴ YAML is the most common and the most widely supported default, so it is the safest choice if you want one note read by many tools.

Structure does not require a database; it requires a convention everyone can read, written in a file you keep. The three dashes are that convention. To keep your metadata where it belongs — inside the note, in plain Markdown, on your own device — write it in a tool that treats your file as the truth, like mnmnote.com.