Updated October 2026.
YAML frontmatter is a block of metadata written in YAML at the very top of a Markdown file, between two lines of three dashes (---). Tools read it to learn things about the file, such as its title, date, tags or publish status, without parsing the content below it. Static site generators, Obsidian, blog CLIs and AI agent skill files all use it.
Here's what it looks like:
---
title: "Blogging Like a Hacker"
date: 2026-08-12
tags:
- markdown
- writing
---
The post content starts here.
This guide covers the syntax, copy-paste examples for the tools you're most likely using, the mistakes that break it, and how to stop hand-writing it.
What is frontmatter?
Frontmatter is any block of structured data at the start of a text file, before the main content. The name comes from book publishing, where "front matter" is the title page, copyright page and table of contents that come before chapter one.
In Markdown files, frontmatter is usually written in YAML, a human-readable data format built on key: value pairs and indentation. That's why you'll see "YAML frontmatter", "YAML front matter", "Markdown frontmatter" and "frontmatter" used for the same thing.
The convention was popularized by Jekyll, the static site generator behind GitHub Pages. GitHub's own docs describe it as "an authoring convention popularized by Jekyll that provides a way to add metadata to pages." It has since spread to almost every tool that treats Markdown files as content.
YAML frontmatter syntax
The triple-dash delimiters
Frontmatter starts and ends with a line of exactly three hyphens:
---
title: My First Post
---
Everything between the two --- lines is parsed as YAML. Everything after the closing line is regular content. The opening --- must be the first line of the file. Nothing can come before it, not even a blank line or a byte-order mark.
Key: value pairs
The basic unit is key: value, with a space after the colon:
title: How to Write Frontmatter
published: true
views: 1024
YAML infers types: true and false become booleans, unquoted numbers become numbers, and everything else is a string. Quote any string that contains a colon or starts with a special character:
title: "Docker vs. Podman: What's the Difference?"
Lists
Lists use a hyphen per item, indented under the key:
tags:
- markdown
- seo
- indie-hackers
The inline form works too: tags: [markdown, seo, indie-hackers].
Nested values
Nest keys with consistent indentation. YAML only allows spaces, never tabs:
author:
name: Jordan Lee
url: https://example.com
Two spaces per level is the common convention. The exact number matters less than using the same number everywhere.
Multi-line strings
For long descriptions, use > to fold lines into one paragraph or | to keep line breaks:
description: >
A long description that wraps across
several lines but renders as one paragraph.
YAML frontmatter examples by tool
The syntax is the same everywhere. What changes is which keys each tool reads.
Jekyll
Jekyll only processes a file as a page or post if it has frontmatter. Even an empty block (--- followed by ---) counts.
---
layout: post
title: "Shipping v2 of our API"
date: 2026-10-01 09:00:00 +0300
categories: [engineering, api]
permalink: /blog/shipping-api-v2/
---
Hugo
Hugo accepts YAML between ---, TOML between +++, or JSON. YAML looks like this:
---
title: "Shipping v2 of our API"
date: 2026-10-01
draft: true
tags: ["engineering", "api"]
summary: "What changed in v2 and how to migrate."
---
The same block in TOML, which Hugo also supports:
+++
title = "Shipping v2 of our API"
date = 2026-10-01
draft = true
+++
Astro
Astro content collections read frontmatter and validate it against a schema you define, so a missing or wrongly typed field fails the build instead of shipping a broken page.
---
title: "Shipping v2 of our API"
pubDate: 2026-10-01
description: "What changed in v2 and how to migrate."
tags: ["engineering", "api"]
draft: false
---
The field names (pubDate vs date, for example) are whatever your collection schema declares.
Next.js and MDX
@next/mdx doesn't parse frontmatter on its own. Most Next.js blogs read it with gray-matter or add remark-frontmatter and remark-mdx-frontmatter to the MDX pipeline. The block itself is standard YAML:
---
title: "Shipping v2 of our API"
date: "2026-10-01"
excerpt: "What changed in v2 and how to migrate."
---
Obsidian
Obsidian shows frontmatter as Properties in its editor, but stores it as plain YAML at the top of the .md file. Built-in keys include tags, aliases and cssclasses. Any other key becomes a custom property.
---
tags:
- project
- blog
aliases:
- API v2 launch
status: draft
published: 2026-10-01
---
Switch a note to Source mode to see the raw YAML.
AI agent skill files (SKILL.md)
Frontmatter now configures AI agents too. A Claude Code skill is a folder with a SKILL.md file whose frontmatter tells the agent what the skill is and when to load it. The two required fields are name and description:
---
name: release-notes
description: Write release notes from the git log. Use when the user asks for a changelog or release post.
---
# Release notes
Steps the agent follows go here.
The agent reads only the frontmatter until it decides the skill is relevant, so the description field is doing the job a meta description does for a search engine. Much of the recent growth in searches for "what is frontmatter" likely comes from this.
Want a complete, working example? The Claude for SEO workflow includes a copy-paste SKILL.md that has Claude read your Google Search Console data over MCP and suggest fixes for your posts.
Blog publishing tools
Markdown blog tools read the same block to set the post's title, URL and status instead of making you fill in a web form. Blogizi's format looks like this:
---
title: "Shipping v2 of our API"
description: "What changed in v2 and how to migrate. Under 160 characters."
keyword: "api versioning"
slug: shipping-api-v2
status: draft
---
The full field list is in the Markdown frontmatter docs.
Common frontmatter fields for a blog post
Names vary by tool, but most expect some version of these:
| Field | What it does | Example |
|---|---|---|
title | Headline and <title> tag | "Shipping v2 of our API" |
description | Meta description and post summary | One sentence, under 160 characters |
date | Publish date | 2026-10-01 |
slug | URL segment | shipping-api-v2 |
tags | Archive pages and related posts | [engineering, api] |
status / draft | Draft or live | draft or draft: true |
image / cover | Social preview or hero image | /images/v2.png |
Common YAML frontmatter mistakes (and fixes)
Missing or misplaced delimiters. A missing closing ---, or a blank line before the opening one, makes the parser fail or render your metadata as page content. Fix: make --- the first line and close the block.
Unquoted colons. title: Docker vs. Podman: What's the Difference? has two colons, so YAML reads the second as a new key. Fix: quote the value.
Values that look like other types. version: 1.10 becomes the number 1.1. country: NO can become false in YAML 1.1 parsers. Fix: quote anything that must stay a string.
Tabs. YAML doesn't allow tab indentation. Fix: set your editor to insert spaces in .md and .yaml files.
Inconsistent indentation. One extra space under a list or nested key breaks the structure. Fix: pick two spaces and stick to it.
Duplicate keys. Most parsers keep the last value and drop the first, silently. Fix: search the block for the key before adding it.
Dates parsed as dates. Unquoted 2026-10-01 becomes a date object in most YAML libraries. Some tools want a plain string. Fix: date: "2026-10-01".
Special characters at the start. Values beginning with @, `, *, &, !, % or # have special meaning in YAML. Fix: quote them.
To check a block quickly, paste it into any YAML validator, or run npx js-yaml file.yaml on just the frontmatter.
YAML vs TOML vs JSON frontmatter
YAML between --- is the default almost everywhere. Hugo also accepts TOML (between +++) and JSON. Obsidian accepts JSON but saves it back as YAML. Unless a tool's docs say otherwise, use YAML. It's the format the widest range of Markdown tooling expects.
FAQ
What does frontmatter mean in Markdown? It's the metadata block at the top of a Markdown file, usually YAML between two --- lines. It describes the file rather than being part of its content.
Is frontmatter part of the Markdown spec? No. CommonMark and GitHub Flavored Markdown don't define it. It's a convention that tools agree on, which is why some renderers show it as a table or a horizontal rule instead of hiding it.
Does GitHub render YAML frontmatter? GitHub shows frontmatter in .md files as a small table at the top of the rendered file instead of hiding it.
Can I use frontmatter without a static site generator? Yes. Obsidian, many note apps, blog CLIs and agent tools read it directly from the file.
Stop hand-writing it
Once you've written frontmatter a few times, the hard part isn't the syntax. It's remembering the field names and keeping descriptions under 160 characters. Blogizi's free Markdown Frontmatter Generator outputs a correct block (title, description, keyword, slug, date, status) to paste at the top of a file, no account needed. If you need the post as HTML instead, the Markdown to HTML converter handles that in the browser.
If you're publishing a blog from Markdown, Blogizi reads this exact frontmatter and handles the sitemap, canonical URL, schema and OG image for you. Write the file (or have your agent write it), then stage it as a draft or publish it straight away:
blogizi draft ./posts/my-post.md # save as a draft to review first
blogizi publish ./posts/my-post.md # go live now
Want your agent to do this on a schedule? See automated blogging with your own AI agent: it drafts on a timer, and nothing goes live until you approve it.
Writing in Obsidian instead? The Blogizi Obsidian plugin uses the same fields.