Markdown Front Matter: YAML Metadata at the Top of a File
By the MDConverter team · Updated · 2 min read
Quick answer
Front matter is a block of metadata at the very top of a Markdown file, written in YAML between two lines of three dashes (---). It holds data about the document — title, date, tags, author, draft status — that site generators (Hugo, Jekyll, Astro, Docusaurus, Eleventy) and note apps (Obsidian Properties) read, while the rest of the file is the content. It is not part of Markdown itself, so plain renderers either hide it or show it as a table.
Syntax
The block must be the first thing in the file — no blank lines or spaces before the opening ---.
---
title: "Getting started with Markdown"
date: 2026-10-10
tags: [markdown, tutorial]
draft: false
author:
name: MDConverter team
---
# Getting started with Markdown
The article content starts here.YAML rules that matter
key: valuewith a space after the colon.- Quote strings that contain a colon,
#, or start with a special character:title: "Step 1: Install". - Lists as
[a, b]or one- itemper line. - Indent with spaces, never tabs, for nested values.
- Dates in
YYYY-MM-DDform are read as dates by most tools. - Booleans
true/false; beware that some older YAML parsers also treatyes/noas booleans.
Common fields by tool
| Tool | Typical fields |
|---|---|
| Hugo | title, date, draft, tags, categories, slug, weight |
| Jekyll | layout, title, date, categories, permalink, published |
| Astro / Eleventy | title, description, pubDate, layout, tags (Astro validates them with content-collection schemas) |
| Docusaurus | id, title, sidebar_label, sidebar_position, slug, description |
| Obsidian (Properties) | tags, aliases, cssclasses, plus any custom field |
| SEO plugins | description, image, canonical |
Hugo also accepts TOML front matter between +++ lines and JSON in braces.
Front matter outside websites
- Pandoc reads
title,author,dateandabstractfor the title block of PDFs and Word documents. - Obsidian shows front matter as editable Properties and uses
tagsandaliasesfor search and links. - Prompt and agent files for AI tools increasingly use front matter for settings such as a name and description.
Front matter when converting
When you convert a file that starts with front matter, decide whether the metadata belongs in the output. Markdown to JSON and Markdown to YAML are useful for pulling structured data out of documents, and YAML to Markdown turns a YAML file into readable Markdown documentation. For Word or PDF output, delete the front matter block first so it does not appear as text at the top of the document.
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
| Front matter shows as text or a horizontal rule | The opening --- must be on line 1, with nothing (not even a blank line or BOM) before it. |
| Build fails with a YAML error | Quote values that contain : or start with [, {, *, &, !, |, >, % or @. |
| Tags are not recognised | Use a YAML list (tags: [a, b] or one - a per line), not a comma-separated string. |
| Indentation error | Replace tabs with spaces. |
Tools for this
- Markdown to JSON Convert Markdown to Structured JSON Format
- Markdown to YAML Convert Markdown into Human-Readable YAML Format
- YAML to Markdown Convert YAML Configurations to Clean Markdown Documentation
- Markdown Formatter Tidy messy Markdown: consistent lists, headings, tables and spacing, with a linter for the rest.
Frequently Asked Questions About Front matter (YAML metadata)
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Flavors: CommonMark vs GitHub Flavored Markdown and More — Why the same Markdown renders differently, and what each major flavor adds.
- How to Write Comments in Markdown — Leave notes in a Markdown file that never appear on the rendered page.
- Markdown Headings: Syntax, Levels and Linking to a Heading — Heading levels, the setext alternative, anchor links and the mistakes that break headings.