Right, let’s talk about the three ways you can tell your static site generator (or any other tool) what your content is about before it even reads the first paragraph. We call this “front matter,” and it’s the little data packet that lives at the top of your content files. It’s where you set the title, the publish date, the tags, and whatever else your heart desires. The format you choose says a lot about you, and at least two of these choices are correct.

The Big Three: A Quick Rundown

You’ve got three main players here, each with their own philosophy.

  • YAML (---): The people-pleaser. Human-readable, forgiving, and the default for most tools like Jekyll, Hugo, and Eleventy. It uses triple dashes as delimiters.
  • TOML (+++): The precisionist. Aims for a clear, unambiguous spec. Beloved by the Hugo community and anyone who has ever been burned by YAML’s quirks. It uses triple pluses.
  • JSON ({}): The utilitarian. The machine loves it. It’s familiar, universally supported, and brutally strict. It uses curly braces.

The tool you’re using will almost certainly tell you which one(s) it supports. The real fun begins when you have to choose.

YAML: The Charming Mess

YAML (YAML Ain’t Markup Language) is the de facto standard, and for good reason. It’s clean, it doesn’t require much punctuation, and it’s easy to write. But oh, the places you will stumble.

The biggest thing to remember with YAML is indentation matters. Two spaces. Not tabs, not four spaces. Two. Get this wrong and your entire site will explode. Well, it’ll throw a cryptic error, which is basically the same thing.

---
title: "My Excellent Blog Post"
date: 2023-10-26T07:00:00Z
tags:
  - web-dev
  - javascript
  - sass
draft: false
author:
  name: "Jane Doe"
  twitter: "janedoe"
---

See? Simple. But let’s talk about the landmines. Want to write a string with a colon in it? You’ll probably need to quote it: title: "This: has a colon". Otherwise, YAML might think it’s a new key-value pair. Numbers can be weird, too. The string '079' is different from the integer 079 (which YAML might interpret as an octal number, because why not?). Just quote things if you’re unsure. It’s the duct tape of YAML.

Multiline strings are where YAML’s “features” truly shine. You have like, eight different ways to do it, each with subtly different behavior regarding newlines and indentation. The | (literal block) and > (folded block) are your friends, but they require a ceremony of correct indentation that would make a medieval scribe proud.

description: >
  This is a long description that will be
  folded into a single line of text because
  I used the greater-than symbol.

code_example: |
  This will preserve all my newlines
  and indentation exactly as I write it.
  Perfect for code snippets.

TOML: The Pedant’s Paradise

TOML is for those of us who look at YAML’s “just wing it” attitude and say, “No. We are going to define rules and we are going to follow them.” It’s explicitly designed to be a minimal configuration file format. There’s less ambiguity, which is a blessing.

Its killer feature? Inline tables. They are a thing of beauty for simple, nested data without the indentation headache of YAML.

+++
title = "My Excellent Blog Post"
date = 2023-10-26T07:00:00Z
tags = ["web-dev", "javascript", "sass"]
draft = false

[author]
name = "Jane Doe"
twitter = "janedoe"
+++

Notice the quotes are mandatory for strings. The equality signs are mandatory. This is not a suggestion. This is the law. And I find it comforting. There’s no guessing. The [author] line denotes a table, which is TOML’s way of handling nested objects. It’s explicit and easy to parse, both for machines and for my tired eyes at 2 AM.

The only real “gotcha” is that TOML can feel a bit more verbose for complex, deeply nested structures. You’re defining tables all the way down. But that verbosity is the price of clarity, and it’s a price I’m often willing to pay.

JSON: The Machine’s Native Tongue

If you’re using JSON in your front matter, you are either a robot, building a tool for robots, or you just really hate yourself. I’m mostly kidding. JSON is fine. It’s ubiquitous. Every programming language on earth can parse it without breaking a sweat. But for humans to write and read at the top of a Markdown file? It’s a chore.

The strict requirement for double quotes, commas, and curly braces is just noisy in this context. One missing comma and the whole thing is invalid.

{
  "title": "My Excellent Blog Post",
  "date": "2023-10-26T07:00:00Z",
  "tags": ["web-dev", "javascript", "sass"],
  "draft": false,
  "author": {
    "name": "Jane Doe",
    "twitter": "janedoe"
  }
}

It’s… fine. It works. But it lacks the lightness of YAML or the clarity of TOML for this specific use case. You can’t add comments (// like this), which is a deal-breaker for configuration. The only reason to use JSON is if your tooling forces you to, or if you’re automatically generating the front matter from another process.

So, Which One Should You Use?

  • Use YAML if you’re working with a tool that defaults to it (like Jekyll or Eleventy) and you value quick, easy-to-write syntax. Just stay vigilant about indentation and quoting.
  • Use TOML if you value unambiguous correctness over conciseness, or if you’re in the Hugo ecosystem where it’s a first-class citizen. Its inline tables are a godsend.
  • Use JSON almost never for hand-writing front matter. Seriously. Let it be the data interchange format it was born to be, not something you manually type between your Markdown.

The best format is the one that causes the least amount of swearing for you and your project. For me, that’s increasingly TOML, but I’ve written enough YAML in my life to fill a library, and it mostly worked. Mostly.