Markdown Frontmatter Explained (And Why Apps Disagree About It)

Frontmatter is the block at the top of a markdown file that most tools read and few agree on.

---
title: Quarterly planning
tags: [work, planning]
date: 2026-08-18
---

The note itself starts here.

Three dashes, some YAML, three dashes, at the very top of the file with nothing above them.

What it is for

Everything the note is about, as opposed to the note itself. Tags, dates, status, source. Apps use it to filter, sort and group without parsing the body.

Because it is plain YAML in a plain text file, it stays readable whatever you open the file with, which is the whole reason to use it rather than an app's internal metadata.

Why apps disagree

Frontmatter is a convention, not a specification. Nothing defines which fields exist or what they mean, so implementations diverge in ways that are invisible until they bite:

Tags. Some apps want a YAML list, others a comma-separated string, others read inline #hashtags from the body and ignore frontmatter entirely.

tags: [work, planning]      # list
tags: work, planning        # string

Both are valid YAML. They are not the same value, and an app expecting one will often silently ignore the other.

Dates. Quoted or unquoted, and with or without a time, changes whether YAML parses it as a date or a string.

Custom fields. An app that does not recognise a field should preserve it untouched. Not all of them do, and the ones that rewrite the file are the ones to watch.

What to actually use

Small is better, because every field is manual maintenance:

• tags, as a YAML list. The most portable choice.
• date, only if the filename does not already carry it.
• aliases, if your app supports linking by them.

Skip title if the filename already is the title, which it usually is. Skip status and priority unless something actually reads them, because hand-maintained state goes stale within a fortnight.

The failure mode worth knowing

The real risk is not disagreement, it is destruction.

If an app parses your file into its own model and writes it back out, any frontmatter field it did not understand can vanish. Plugin-specific fields are the usual casualty, and you find out much later.

This is the same problem as markdown editors rewriting your files, and it has the same test: copy a note with unusual frontmatter, edit one word in the body, save, and diff.

An app that leaves fields it does not understand exactly as written is safe to point at a vault built by other tools. TypeFire preserves plugin frontmatter as written, which is part of why a 10,012 file vault including plugin metadata could be opened with zero files modified.

Frontmatter versus inline tags

Both work, and it is worth choosing deliberately.

Frontmatter tags are structured, easy to query, and invisible in the rendered note.

Inline #tags are written where the idea is, so they carry context, but they clutter the prose.

Pick one and be consistent, because a vault split between both conventions searches badly in every app.