MarkdownPaper Open reader

Guide

Markdown frontmatter

Frontmatter is a block of settings at the very top of a Markdown file, between two lines of ---. It is written in YAML, holds facts about the document, such as its title and date, and is not shown as part of the page.

You write

---
title: Trip notes
date: 2026-03-14
tags: [travel, italy]
draft: true
---

# Trip notes

The text of the document starts here.

You see

Trip notes

The text of the document starts here.

The block disappears on the right: the reader keeps it, but does not print it on the page.

3 min read8 sectionsUpdated 1 Oct 2026

On this page

What it is for

Frontmatter is for the tools that use the file, not for the person reading it.

  • Static site generators such as Jekyll, Hugo, Astro and Eleventy read the title, date and layout to build each web page.
  • Note apps such as Obsidian show it as the note's properties, and use the tags to find notes.
  • Documentation tools read a title, a sidebar position or a description for search results.
  • AI tools read it at the top of instruction files and skills, to decide when the file applies.

The guides on this site are written this way: each one starts with a title, a description and its place in the list.

How to write YAML frontmatter

  • The first line of the file is ---, with nothing before it, not even an empty line.
  • Each setting is a name, a colon, a space and a value.
  • The block ends with another ---.
ValueWrite
Texttitle: Trip notes
Text with a colontitle: "Rome: day one"
A datedate: 2026-03-14
Yes or nodraft: true
A listtags: [travel, italy]

A longer list can go one item per line:

tags:
  - travel
  - italy

TOML frontmatter

Hugo also accepts TOML, between lines of +++, with = instead of a colon.

You write

+++
title = "Trip notes"
draft = true
+++

The page starts here.

You see

The page starts here.

Which settings to use

There is no standard list. Each tool reads its own names, so check the documentation of the tool that will use the file. title, date, description and tags are the most common.

How apps show it

AppFrontmatter
GitHubShown as a small table at the top
MarkdownPaperHidden, YAML and TOML
ObsidianShown as properties
Static sitesUsed to build the page, not shown

Common problems

  • The block shows as a line and a heading. Something is before the first ---, often an empty line. The block must be the very first thing in the file.
  • A tool cannot read the title. A value with a colon in it needs quotes.
  • Tabs in the block. YAML only accepts spaces for indenting.

Questions

What is the --- at the top of a Markdown file?

It opens the frontmatter, a block of settings in YAML that ends at the next ---.

Is frontmatter part of Markdown?

No. It is a convention that most Markdown tools agree on. Apps that do not know it show it as text, usually as a line with a heading under it.

Is frontmatter required?

No. A Markdown file without it is perfectly fine. Add it only when a tool needs it.

Next