Front Matter and Metadata

What front matter is

Front matter is a block of structured data at the very top of a text file, separated from the content by delimiter lines. The tool that processes the file reads the block, removes it from the content, and uses the values for something else: the page title, the publication date, which template to use, which tags to list the page under.

Here is a runbook from Kestrel Energy's portal repository, with front matter above the Markdown:

---
title: Restart the customer portal
owner: Ravi Kumar
last_reviewed: 2026-10-05
tags: [portal, runbook]
---

# Restart the customer portal

Use this runbook when both web servers stop responding.

A documentation site built from this file shows the heading and the paragraph, puts "Restart the customer portal" in the browser tab, lists the page under the tags portal and runbook, and can show the owner and review date in a footer. The front matter itself never appears as text.

The name comes from book publishing, where the front matter is everything before the main text: title page, copyright page, table of contents.

Document metadata

Document metadata is data about a document rather than its content: who wrote it, when, for whom, what it is about, how current it is. Word processors keep it in file properties, HTML pages in <head> elements such as the meta description. A Markdown file is just text, so front matter is where its metadata lives, in the same file and under the same version control.

Typical keys in documentation and notes:

Only keys that a tool knows have an effect. A static site generator ignores owner unless a template uses it, but a team can still read it, search for it and check it automatically. Metadata such as an owner and a review date is what keeps runbooks from silently going stale; see Keeping documentation alive.

YAML front matter

YAML front matter is the most common form: YAML between a line of three hyphens at the very start of the file and a second line of three hyphens. Jekyll, which made the convention popular, states the rules plainly: the front matter must be the first thing in the file, and it must be valid YAML set between triple-dashed lines.

Inside the block, the usual YAML structures apply. Here are the values of the runbook above, written out in full:

title: Restart the customer portal
owner: Ravi Kumar
last_reviewed: 2026-10-05
tags:
  - portal
  - runbook
related_incidents: [INC-31902]
reviewed_by_noc: true

• Key: value pairs, one per line, with a space after the colon.
• Lists, either as indented lines starting with - or inline in square brackets.
• Types are guessed from the value: true is a boolean, 2026-10-05 becomes a date, 42 a number, everything else a string.
• Indentation uses spaces, never tabs.

What a plain renderer shows

Front matter is a convention of tools, not part of CommonMark or GitHub Flavored Markdown. A renderer that does not know about it, such as the one on this site, treats the block as ordinary Markdown. The first --- becomes a horizontal rule. The second --- sits right under text, so it turns that text into a level-2 setext heading:

---
title: Restart the customer portal
owner: Ravi Kumar
tags: [portal, runbook]
---

# Restart the customer portal

Use this runbook when both web servers stop responding.

<hr>
<h2>title: Restart the customer portal
owner: Ravi Kumar
tags: [portal, runbook]</h2>
<h1>Restart the customer portal</h1>
<p>Use this runbook when both web servers stop responding.</p>

The result depends on the YAML inside. With a block-style list, the list items become a Markdown list, and the closing --- follows a list instead of a paragraph, so it stays a horizontal rule:

---
title: Restart the customer portal
tags:
  - portal
  - runbook
---

# Restart the customer portal

<hr>
<p>title: Restart the customer portal
tags:</p>
<ul>
<li>portal</li>
<li>runbook</li>
</ul>
<hr>
<h1>Restart the customer portal</h1>

This is what readers see when a file with front matter is opened in a viewer that does not support it: a package registry, a Markdown preview without the right plugin, a chat message. GitHub handles it better: according to its 2013 announcement, it displays YAML front matter in a rendered file as a small table above the content.

Static site generators

A static site generator is a program that turns a folder of text files (mostly Markdown) and templates into a complete website of plain HTML files, ahead of time. The result needs no database or application server and can be published on any static hosting. Front matter is how each file tells the generator what kind of page it is.

The generators you are most likely to meet, and what they accept:

TOML and JSON front matter

Hugo decides the format by the first line. TOML (Tom's Obvious, Minimal Language) uses +++ and key = value, with strings always in quotes:

+++
title = "Planned maintenance on 7 November"
date = 2026-11-07
draft = false
+++

# Planned maintenance on 7 November

JSON front matter is an object in braces at the top of the file. GitLab also renders all three formats. To any tool that does not know the convention, TOML front matter is simply a paragraph that starts and ends with +++:

+++
title = "Planned maintenance on 7 November"
draft = false
+++

# Planned maintenance on 7 November

<p>+++
title = &quot;Planned maintenance on 7 November&quot;
draft = false
+++</p>
<h1>Planned maintenance on 7 November</h1>

MkDocs' second style, MultiMarkdown-style metadata, is a set of Key: value lines at the top that ends at the first blank line. It reads naturally, but forget the blank line and a tool that does not recognize it merges everything into one paragraph:

Title: Restart the customer portal
Owner: Ravi Kumar
Reviewed: 2026-10-05

# Restart the customer portal

<p>Title: Restart the customer portal
Owner: Ravi Kumar
Reviewed: 2026-10-05</p>
<h1>Restart the customer portal</h1>

Note apps and platforms

Note-taking apps use the same convention. In Obsidian, front matter is called properties: YAML between --- lines at the top of a note, edited in a form above the text. Each property has a type (Text, List, Number, Checkbox, Date, Date & time or Tags), which lets you sort and filter notes by them:

type: meeting
date: 2026-10-01
attendees:
  - Mei Chen
  - Amara Okafor
follow_up: true
tags:
  - service-desk

Because the format is plain YAML in a plain text file, notes stay readable and portable: another tool, a script or a static site generator can read the same properties. More on note apps in Markdown in chat, notes and AI tools.

Mistakes that break front matter

When front matter breaks, the symptom is often confusing: a site build fails with a YAML error and a line number, or worse, the build succeeds and the page shows the raw block as a rule and a heading. The usual causes:

• Something before the first ---: a blank line, a comment, or an invisible byte order mark that some Windows editors add. Then the block may no longer count as the start of the file, and it is treated as Markdown.
• A missing closing ---, so the tool reads the whole document as YAML, or none of it.
• A colon followed by a space inside an unquoted value. YAML reads it as the start of a new key:

title: Outage: Deventer and Zwolle

mapping values are not allowed here
  in "<unicode string>", line 1, column 14:
    title: Outage: Deventer and Zwolle
                 ^

Quote the value, and the problem is gone:

title: "Outage: Deventer and Zwolle"

• Values that YAML reads as another type. version: 1.10 becomes the number 1.1; parsers that follow the older YAML 1.1 rules (PyYAML, for one) read draft: no or a country code NO as the boolean false; 2026-11-05 becomes a date object, which a template may then format differently from what you typed. Quote values that must stay text. The YAML pitfalls section explains these in detail.
• Tabs for indentation, which YAML does not allow.
• Inconsistent keys: tags in one file, Tags or tag in another. YAML keys are case-sensitive, so the tag page silently misses half the documents.

Good practice

• Agree on a small set of keys and write them down, for example in the repository's contributing guide. Five keys that every file has are worth more than twenty that some files have.
• Check front matter automatically. A short script or a schema check in the pipeline can verify that every runbook has an owner and a last_reviewed date that is not older than a year; see GitHub Actions for running such checks on every pull request.
• Never put secrets in front matter. It is part of the file, so it is in the repository history, and generators often expose page variables to templates, feeds and search indexes.
• Quote when in doubt. A quoted string is never misread.