YAML Front Matter in Markdown Files
If you've written a blog post for a static site generator like Jekyll, Hugo, or Astro, you've probably typed YAML without necessarily calling it that. The block at the very top of the file, fenced by --- lines, is YAML front matter.
---
title: "Why I Switched My Blog to Static Hosting"
date: 2026-03-14
tags: [hosting, static-sites, performance]
draft: false
---
The actual Markdown content of your post starts here...What it's actually for
Front matter separates a post's metadata — title, date, tags, whether it's published — from its actual written content. The static site generator reads the YAML block to decide things like the page's URL, its listing on the homepage, and which template to use, then renders everything below the second --- as regular Markdown.
Rules specific to front matter
- The opening and closing
---are required, not optional the way a leading---is in a standalone YAML file — this is how the generator knows where the metadata block ends and the Markdown begins. - Keep the block itself valid YAML — all the normal rules apply: consistent indentation, quote strings that contain colons, and so on.
- Watch out for special Markdown characters inside titles. A title containing a colon, like
title: Docker: A Beginner's Guide, needs to be quoted —title: "Docker: A Beginner's Guide"— or YAML will misread the colon as a new key.
A quick way to catch front matter mistakes
A broken front matter block often doesn't throw a loud error — it can silently cause a post to not build, or to build with a missing title or wrong date. Before committing a new post, copy just the YAML block (without the surrounding --- lines) into our validator to confirm it parses cleanly, especially if the title or tags contain punctuation.