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.

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.

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.

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.

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.

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.

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.

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

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary