This vocabulary follows you everywhere
At some point, almost every tech tool asks you to describe something: a blog post needs a title and a date, a website needs a page description, a config file needs to know which port to run on. The format is almost always the same — a name, a colon, and a value.
Once you understand key-value pairs and data types, you'll recognise this pattern immediately — in Markdown files, JSON configs, API responses, database records, and hundreds of other places. It's one of the closest things technology has to a universal language.
Understanding this vocabulary means you can pick up new tools faster, read unfamiliar files without panic, and write configurations correctly the first time. It's a small investment that pays off constantly.
What is front matter?
Front matter is a block of metadata placed at the very top of a file — before any of the main content — fenced off with three dashes on each side.
Imagine a book. Before you reach chapter one, there's a title page, a copyright page, a table of contents. That isn't the story — it's information about the story: who wrote it, when it was published, what category it belongs to.
Front matter is the same idea for digital files. It's the "information about this file" section, sitting quietly above the main content — invisible to readers but invaluable to the tools processing the file.
Here's what it looks like inside a real Markdown blog post:
--- title: "How I Learned to Stop Worrying" date: 2026-03-15 author: "Alex Chen" published: true tags: ["beginners", "learning"] --- # How I Learned to Stop Worrying The actual article content starts here...
Everything between the --- fences is front matter. Everything below is the content readers actually see. The platform reading this file uses the front matter to sort posts by date, display author names, show or hide drafts, filter by tags, and power search engines.
The format used above is called YAML — the most common front matter format. It's designed to be human-readable. There are others (TOML and JSON), but YAML's clean key: value style makes it the most popular choice in modern tools.
What is a key-value pair?
A key-value pair is the fundamental unit inside front matter. One key. One value. One piece of information stored.
title: "My First Post" ↑ ↑ key value
Think of a paper form — a job application. Each field has a printed label on the left ("First Name:", "Date of Birth:", "Are you available to start immediately?") and a blank box on the right for your answer.
The label is the key. Your answer is the value. A key-value pair is simply one label plus one answer.
The rules are simple:
- The key is always on the left, followed by a colon and a space
- The value is always on the right
- Each pair lives on its own line
- Keys are lowercase, no spaces (use hyphens or underscores:
word-countorword_count)
Forgetting the space after the colon. title:"My Post" will break. It must be title: "My Post" — the space is part of the YAML syntax.
Data types — what kind of value is it?
Every value in a key-value pair has a type. The type tells the computer what kind of thing this value is and what it can do with it. There are six types you'll encounter again and again:
author: "Maria Santos"
rating: 4.5
featured: false
name: "Alex"
email: "a@..."
updated: 2026-03-19
Putting quotes around a boolean or number. Writing published: "true" doesn't give you a boolean — it gives you the text string "true", which behaves differently. Booleans and numbers should never have quotes around them.
A complete Markdown file, annotated
Here's a full blog post file — front matter and content together. Each front matter line shows a different data type:
--- title: "What I Learned at the Conference" ← string date: 2026-03-19 ← date author: "Sam Rivera" ← string published: true ← boolean featured: false ← boolean read_time: 5 ← number (minutes) tags: ["events", "learning", "tech"] ← array seo: ← object (nested) description: "Key takeaways from the event" image: "/images/conference.jpg" --- ## What I Learned at the Conference The article text starts here. Readers only see this section — the front matter is invisible to them.
When a static site generator (like Astro, Hugo, or Jekyll) processes this file, it reads the front matter to build the page: populating the title tag, sorting by date, building the tag index, and passing SEO fields to search engines. The reader sees none of it — only the article.
Where you'll find this pattern in the wild
Key-value pairs aren't just a front matter thing. This pattern is one of the foundations of all computing. Once you can read it, you'll recognise it everywhere:
Markdown / Blogs
Front matter in .md files controls title, date, author, tags, SEO, and draft status.
Static Site Generators
Astro, Hugo, Jekyll, Eleventy all read front matter to build pages, navigation, and sitemaps.
Config Files
package.json, docker-compose.yml, .eslintrc — all key-value pairs describing how tools should behave.
CMS Systems
Contentful, Sanity, Ghost store all content fields as key-value pairs in a database.
API Responses
JSON from any API is key-value pairs. When you fetch data from Spotify or GitHub, you receive a structured object.
Environment Variables
.env files are key-value pairs: API_KEY=abc123. The key names the variable; the value stores the secret.
The mistakes beginners make most often
title:"My Post" → broken. title: "My Post" → correct. The space is required in YAML syntax.
published: "true" is a string, not a boolean. count: "5" is text, not a number. Remove the quotes.
YAML uses indentation (spaces, not tabs) to show nesting. Inconsistent indentation is the #1 cause of YAML parse errors. Use 2 spaces throughout.
Front matter needs three dashes to open and three dashes to close. Without the closing fence, the parser may treat your entire document as front matter.
Most YAML error messages include a line number. Go straight to that line — it's almost always an indentation issue, a missing space after a colon, or a stray character.
The vocabulary you can return to
--- on each side. Invisible to readers; used by tools. name: value. The key names it; the value stores the data. "Hello world" 42 or 3.14 true or false ["a", "b", "c"] key: value syntax.