What Is Frontmatter? Metadata in Markdown Files

Frontmatter is a block of metadata at the top of a markdown file, enclosed by triple dashes (---). It uses YAML syntax to define properties like title, date, author, and tags. Static site generators, documentation tools, and content management systems read frontmatter to configure how the page is built and displayed.

Basic Syntax

Frontmatter sits at the very top of the file, before any content:

---
title: "How to Write a Changelog"
description: "Format, examples, and templates for project changelogs."
author: "david-schemm"
date: 2026-03-04
tags: ["markdown", "changelog"]
---

Your markdown content starts here.

The rules:

• Must be the first thing in the file (no blank lines before it)
• Delimited by exactly --- on its own line (three dashes)
• Uses YAML syntax for key-value pairs
• Ends with a second --- line

Common Frontmatter Fields

Different tools expect different fields, but these are widely supported:

YAML Syntax in Frontmatter

Strings

title: Simple string without quotes
title: "String with special characters: colons, #hashes"
title: 'Single quotes also work'

Quote strings that contain colons, hashes, or brackets to avoid YAML parsing errors.

Numbers and Booleans

readingTime: 5
draft: false
featured: true

Arrays

# Inline format
tags: ["markdown", "tutorial", "guide"]

# Block format
tags:
  - markdown
  - tutorial
  - guide

Dates

date: 2026-03-04
publishedAt: 2026-03-04T10:00:00Z

YAML dates follow ISO 8601 format. Some tools expect just a date; others want a full timestamp with timezone.

Nested Objects

author:
  name: "David Schemm"
  url: "https://davidschemm.com"
  avatar: "/images/david.jpg"

Nested objects are supported by most frontmatter parsers, but not all tools expect them.

How Tools Use Frontmatter

Static Site Generators

Content Collections (Astro)

Astro validates frontmatter against a Zod schema, catching errors at build time:

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishedAt: z.coerce.date(),
    tags: z.array(z.string()),
    readingTime: z.number(),
  }),
});

If a markdown file has a missing or invalid field, the build fails with a clear error. This prevents publishing posts with missing titles or broken dates.

Obsidian

Obsidian reads frontmatter for its properties system:

---
aliases: ["my-note", "alternative-name"]
cssclass: "wide-page"
tags: [project, active]
---

Obsidian uses aliases for note linking, cssclass for styling, and tags for organization. It displays frontmatter in a properties panel above the content.

Frontmatter vs Content

A common question: should metadata like the title go in frontmatter, in the content as an H1, or both?

Most blog engines and documentation tools pull the title from frontmatter and inject it into the page template. If you also write an H1 in the content, you get a duplicate title. Check your tool’s documentation for the expected pattern.

TOML and JSON Frontmatter

While YAML is the most common format, some tools support alternatives.

TOML frontmatter (Hugo):

+++
title = "My Post"
date = 2026-03-04
tags = ["markdown", "guide"]
+++

Content here.

TOML uses +++ delimiters instead of ---.

JSON frontmatter (rare):

{
  "title": "My Post",
  "date": "2026-03-04"
}

Content here.

JSON frontmatter has no delimiters; the parser detects the opening {. This is uncommon and not recommended due to readability issues.

Common Mistakes

Content before frontmatter. The --- block must be the very first thing in the file. A blank line or any text before it causes the parser to treat it as regular content:

<!-- Wrong: text before frontmatter -->
Some text
---
title: "My Post"
---

Unquoted strings with special characters. Colons and hashes in YAML values need quotes:

# Wrong: YAML parse error
description: How to use: advanced features

# Correct
description: "How to use: advanced features"

Tab indentation in YAML. YAML requires spaces, not tabs. Tabs cause parse errors:

# Wrong: tabs
tags:
  - markdown
  - guide

# Correct: spaces
tags:
  - markdown
  - guide

FAQ

What is frontmatter in markdown?

Frontmatter is a YAML metadata block at the top of a markdown file, delimited by ---. It stores structured data (title, date, tags, author) that tools use to build pages, generate SEO meta tags, sort content, and more.

Is frontmatter part of the markdown specification?

No. Frontmatter is not part of CommonMark or GFM. It is a convention adopted by static site generators (Jekyll, Hugo, Astro, Next.js) and note-taking tools (Obsidian). Markdown renderers that do not expect frontmatter will display it as text.

What happens if I make a YAML syntax error in frontmatter?

Most build tools (Astro, Next.js, Hugo) fail the build and show an error with the line number. Obsidian may show the raw YAML at the top of the note. YAML errors are usually caused by unquoted special characters or tab indentation.

Can I use frontmatter in GitHub README files?

GitHub does not process frontmatter in rendered markdown. The --- block appears as a horizontal rule, and the YAML content renders as text. Frontmatter is designed for tools that build pages, not for raw markdown rendering.

Try It Out

Write a markdown document with frontmatter and preview it in the MDtoLink editor. Publish to a shareable URL when you’re ready.

For the full markdown syntax, see the markdown cheat sheet. For a broader introduction, see What Is Markdown?.