Front Matter

What Front Matter Is

A metadata block at the very top of a Markdown file, delimited by a fence, consumed by the tool that processes the file and removed before rendering. It is not part of any Markdown spec, so a plain Markdown renderer treats it as content.

The block must start on line 1. A blank line, a BOM, or a comment before it means the tool does not recognize it, and the delimiters render as a horizontal rule followed by text.

---
title: Getting Started
date: 2026-03-14
---

# Getting Started

The body starts here.

On GitHub, YAML front matter in a .md file is rendered as a small table rather than hidden, which surprises people who wrote it for a static-site generator.

YAML Front Matter

Three hyphens above and below, YAML in between. This is the dominant format by a wide margin.

---
title: "Deploying to production"
description: A short summary used for meta tags.
date: 2026-03-14
lastmod: 2026-04-02
draft: false
weight: 10
author: Pablo Valdes
tags:
  - deployment
  - ops
categories: [guides]
slug: deploying
aliases:
  - /old-url/
image: ./cover.png
---

Rules that bite:

• The closing --- is required. Without it the whole file is parsed as YAML and usually fails.
• A value containing :, #, @, or a leading digit-plus-colon needs quotes. title: Notes: part 2 is a YAML error.
• Indentation is significant, and tabs are illegal in YAML.
• Unquoted yes, no, on, off, true, and false become booleans. A version string like 1.0 becomes a float, and 1.10 becomes 1.1. Quote anything that must stay a string.
• Dates are parsed as dates by most loaders, so quote them if a tool expects a string.

---
title: "Notes: part 2"      # quoted, because of the colon
version: "1.10"             # quoted, or it becomes 1.1
published: "no"             # quoted, or it becomes false
---

TOML and JSON Front Matter

Hugo accepts all three formats and picks by delimiter.

+++
title = "Deploying to production"
date = 2026-03-14
draft = false
weight = 10
tags = ["deployment", "ops"]

[params]
  showToc = true
+++

{
  "title": "Deploying to production",
  "date": "2026-03-14",
  "draft": false,
  "tags": ["deployment", "ops"]
}

TOML uses +++ as its delimiter and = for assignment, and it has real types, so version = "1.10" stays a string without special care. JSON front matter is delimited by the braces themselves in Hugo, and is the least common of the three.

Pick one per project. A mixed repository means every tool that reads the files has to support all three.

What Consumes It

Pandoc is worth noting separately: it reads a YAML block anywhere in the file, not only at the top, and treats it as metadata rather than content.

Common Keys

The names are conventions, not a standard, and every generator has its own. The set that recurs:

Check the target generator's documentation before inventing a key. An unknown key is usually ignored silently, which is how a typo in draft publishes a draft.

Reading It Yourself

If you process Markdown in your own code, a front-matter parser splits the block from the body before you hand the body to a Markdown renderer.

import matter from "gray-matter";

const { data, content } = matter(fileContents);
// data    -> the parsed front matter object
// content -> the Markdown body, front matter removed

import frontmatter

post = frontmatter.load("post.md")
print(post["title"])
print(post.content)

# Extract the block with awk, no dependency
awk '/^---$/{n++; next} n==1' post.md

Always parse rather than regex, because a --- inside the body (a thematic break, or a fence containing one) will trip a naive pattern.

Gotchas

• A --- line early in the body can be mistaken for a closing delimiter by a sloppy parser, and a thematic break on line 2 collides with front matter entirely.
• A missing closing delimiter produces a build error that names the whole file, not the line, and is easy to miss.
• Windows line endings break some strict YAML loaders. Keep the file LF.
• Tabs in YAML are a hard error. Configure the editor to use spaces for .md.
• GitHub renders it as a table, so a README with front matter looks odd in the repository view even though the site is correct.
• Front matter is not Markdown, so it does not appear in a word count, a diff summary, or a plain-text preview the way body content does.