YAML Front Matter

By the end of this lesson you'll add a metadata block to the top of any Markdown file — the title, date, tags, and layout that static site generators read to organise and publish your pages.

Learn YAML Front Matter in our free Markdown course — an interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn

💡 Real-World Analogy

Front matter is like the label on a parcel . The parcel itself (your Markdown body) holds the contents, but the label on top tells the sorting office everything it needs to route it: who it's for, when it was posted, which shelf it belongs on. A static site generator is that sorting office — it reads the label ( title , date , tags ) to decide what to call the page, where to list it, and whether to ship it at all.

1. What Front Matter Is

Front matter is a small block of metadata placed at the very top of a Markdown file, before any body content. In its most common form it's written in YAML and fenced by a line of three hyphens ( --- ) above and below. Everything inside the fences is data about the page — not part of the page text. The body of the document begins immediately after the closing --- line.

• title = My First Post
• date = 2026-06-21
• layout = post
• draft = false
• tags = [markdown, tutorial, beginners]

The body content renders below, exactly as normal Markdown.

2. Keys, Values, and Lists

Inside the block you write key: value pairs — a key, a colon, a space, then the value. A value can be text ( title: My Post ), a number, or a boolean ( draft: false ). For multiple values, YAML uses a list : put the key with a colon, then each item on its own indented line starting with - and a space. Indentation is meaningful in YAML, so keep it consistent — usually two spaces.

• title — the page or post title
• date — publication date (often YYYY-MM-DD)
• tags / categories — a list used to group content
• layout / template — which template renders this page
• draft — true to keep the page out of the published build

🎯 Your Turn #1: write the fields

Fill in the three blanks so the program prints a valid front matter block with a title, date, and draft flag, then run it.

3. Who Reads Front Matter

Front matter is only useful to a tool that knows to look for it. The big consumers are static site generators : Jekyll popularised the YAML block, and Hugo and Hexo use it too. Note-taking apps such as Obsidian read front matter (it calls them "properties") to store tags and aliases. In every case the generator parses the fields, then hands the body content to the Markdown renderer.

Here's a worked example that prints a real YAML block you can copy. Run it, read each printed line, then drop it at the top of a .md file in a generator to see the fields take effect.

🎯 Your Turn #2: add a tags list

Fill in the blanks so the program prints a tags list with two indented items. Watch the two-space indent and the - prefix — that's what makes it a YAML list.

4. Other Formats: TOML and JSON

YAML is the most common, but it isn't the only choice. Hugo and a few other tools also accept TOML front matter, fenced by +++ lines and using key = value syntax. Some tools accept JSON front matter — a plain JSON object in curly braces at the top of the file. The fence you choose tells the parser which format to expect.

Common Errors (and the fix)

• My metadata is ignored. The opening --- wasn't the very first line. Remove any blank line, comment, or heading above it.
• My list isn't recognised. List items need a hyphen and a space, indented under the key. tags: then - markdown on the next line.
• YAML build error about indentation. YAML is whitespace-sensitive and dislikes tabs. Use spaces, and keep the same indent for items at the same level.
• My value broke the parser. Values containing a colon, # , or leading special characters may need quotes: title: "Notes: part 1" .
• I mixed fences. A +++ opener needs a +++ closer (TOML); don't pair it with --- (YAML).

📋 Quick Reference — Front Matter

Concept

Syntax

YAML fence

--- (open and close)

Key/value

title: My Post

Boolean

draft: false

List

tags: then indented - item lines

TOML fence

+++ with key = value

JSON

{ "title": "My Post" }

Mini-Challenge: A Complete Post Header

No blanks this time — just a brief and an outline. Use console.log to print the source for a post that combines everything: a fenced YAML block with title, date, layout, and a tags list, then an H1 below it.

Pro Tips

• 💡 Quote ambiguous values. If a title contains a colon or starts with a special character, wrap it in quotes so YAML parses it as plain text.
• 💡 Keep keys lowercase. Generators usually expect lowercase field names like title and date ; mixed case can be missed.
• 💡 Use draft while writing. Set draft: true to keep a half-finished post out of the build, then flip it to false when ready.
• 💡 Validate your YAML. A stray tab or missing space causes a build error; a YAML linter catches it before you publish.

Frequently Asked Questions

Q: Will front matter show up when I view the Markdown on GitHub?

GitHub renders YAML front matter as a small metadata table at the top rather than as raw text, but plain Markdown viewers may show the --- block literally. It's really meant for a generator that parses it.

Q: Is front matter part of the Markdown spec?

No. CommonMark does not define front matter; it's a convention added by tools. That's why support and exact fields vary between Jekyll, Hugo, and others.

Yes. You can add custom keys (like author or featured ) and read them inside your templates. The generator ignores fields it doesn't recognise unless your theme uses them.

Use whatever your generator defaults to; YAML ( --- ) is the most widely supported. Hugo accepts all three, so the choice there is mostly personal preference.

Lesson Complete! 🎉

• ✅ Front matter is a metadata block fenced by --- at the very top of the file
• ✅ Fields are key: value pairs, with lists written as indented - items
• ✅ Common fields include title , date , tags , layout , and draft
• ✅ Static site generators (Jekyll, Hugo, Hexo) and tools like Obsidian read it
• ✅ TOML ( +++ ) and JSON ( { } ) are alternative front matter formats

Where to go next: now that your pages carry metadata, learn to embed visuals in them. Continue to Diagrams with Mermaid to turn fenced code blocks into flowcharts and sequence diagrams.

Practice quiz

Continue this course

• Previous: Advanced Markdown Features
• Next: Diagrams with Mermaid