Frontmatter Basics

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Write the YAML block at the top of a Markdown file. Fix a title that breaks the parser, learn keys, values, quotes, lists, groups and long text, catch the traps that silently change data, and see why AI skills depend on frontmatter.

The Title That Broke the Page

The order-support docs site reads a small block of data at the top of every page. Asha gives the refund page a title, and the site build fails.

One colon too many

---
title: Refunds: the rules
owner: support-team
---

# Refunds

Refunds are allowed within 30 days.

Open the Outline tab. Under "Frontmatter", it shows an error on line 2. The title contains : , a colon and a space. In this block, : is what separates a name from its value. So the parser sees two separators on one line, and gives up.

The fix is two quote marks: title: "Refunds: the rules". Try it now, and the error is replaced by the two fields.

That block at the top is called frontmatter. In this lesson, you will learn how to write it, and the small mistakes that break it.

In simple words: frontmatter is a short list of name: value lines between two --- lines, at the very top of a file. It is data about the file, not part of the page.

TL;DR

• Frontmatter is data about a file: its title, description, owner, tags. It sits between two --- lines at the very top.
• It is written in YAML, a simple data format: one key: value per line.
• Put a value in quotes if it contains : , starts with a special character, or has a #.
• Indent with spaces, never tabs. Keys at the same level must line up exactly.
• Lists are written [a, b] or as lines that start with - .
• Docs sites read frontmatter and hide it. Plain CommonMark shows it as a divider line and a heading.
• AI tools depend on frontmatter too: a SKILL.md file needs a name and a description in it.

A Real-World Example

Think about a parcel.

The box holds the things you sent. The label on the outside holds facts about the box: who it is for, where it is going, how much it weighs. The courier reads the label. They never open the box.

Frontmatter is the label. The Markdown below it is the box. Docs sites, blog tools and AI agents read the label to decide what to do with the file: what title to show, which menu to put it in, when to load it.

What You Will Learn

In this lesson, you will learn:

1. What frontmatter is, and where it goes.
2. How to write YAML keys and values.
3. When to use quotes.
4. How to write lists, groups and long text.
5. The YAML traps that change your data without an error.
6. Why AI tools rely on frontmatter.

Cheat Sheet

Frontmatter in one block

---
title: Refund policy
description: "Refund rules: windows, limits and approvals."
owner: support-team
version: "2.4"
draft: false
tags: [refunds, billing]
reviewers:
  - Asha
  - Ravi
contact:
  team: support
  channel: "#refunds"
---

# Refund policy

Refunds are allowed within 30 days.

Open the Outline tab. Under "Frontmatter", each key is listed with its type: a string, a number, a true-or-false value, a list or a group. The Rendered tab, on the Docs site flavour, shows no trace of the block. Now switch to CommonMark and look at the top of the page.

What Frontmatter Is

Data About the File

Some facts belong to a file, not to its text. The page title for the browser tab. A short description for search results. Who owns the page. Whether it is a draft.

You could write these in the text. But then a program would have to guess where they are. Frontmatter puts them in one fixed place, in a fixed format, so programs can read them exactly.

You saw this idea in the very first lesson: Markdown for things people read, YAML or JSON for things programs read. Frontmatter lets one file hold both.

The Shape

Frontmatter has three strict rules.

1. The very first line of the file is exactly ---. Not a blank line, not a space, not a title.
2. Then come the key: value lines.
3. Then a line that is exactly --- ends the block.

The smallest frontmatter

---
title: Refund policy
---

# Refund policy

Refunds are allowed within 30 days.

Add a blank line above the first ---. Open the Outline tab: the frontmatter is gone, because it no longer starts on the first line. The Rendered tab now shows a divider and the text title: Refund policy as a heading.

What Each Renderer Does

This is why the boxes in this lesson start on the Docs site flavour.

Writing YAML

Keys and Values

YAML is a format for writing data as text. In frontmatter, each line is a key, a colon, a space, and a value.

Four kinds of value

---
title: Refund policy
version: 2
draft: false
reviewed:
---

# Refund policy

Open the Outline tab. YAML decides the type of each value by how it looks:

• Refund policy is a string: text.
• 2 is a number.
• false is a boolean: true or false.
• An empty value is null: nothing.

The space after the colon is required. title:Refunds with no space is not a key and a value. It is one long string, and the whole block is no longer a list of keys.

When to Use Quotes

Most text needs no quotes. But some characters have a job in YAML. If your value contains one, put the whole value in double quotes.

Values that need quotes

---
title: "Refunds: the rules"
channel: "#refunds"
author: "@asha"
note: "*important*"
plain: Refund rules for support staff
---

# Refunds: the rules

Now remove the quotes from note and look at the Outline tab. The parser reads *important* as a YAML alias, a feature for reusing values, and fails.

Lists, Groups and Long Text

Lists

A list is several values under one key. YAML has two ways to write one.

Two ways to write a list

---
tags: [refunds, billing, support]
reviewers:
  - Asha
  - Ravi
---

# Refund policy

Both are lists. The first is short, on one line. The second puts each item on its own line, with two spaces, a dash and a space. Use the long form when items are long or there are many of them.

Groups

A group is a key whose value is more keys. YAML uses the indent to show what belongs inside.

A group of keys

---
owner:
  team: support
  lead: Asha
  channel: "#refunds"
---

# Refund policy

team, lead and channel all belong to owner, because they are indented under it by the same two spaces.

The indent must be spaces, and every key in the group must line up exactly. Add one more space in front of lead and look at the Outline tab.

Long Text

For a value that runs over several lines, put | or > after the colon, then indent the text below it.

Long text, kept or folded

---
steps: |
  Open the order.
  Check the receipt.
folded: >
  Refunds are allowed within 30 days
  of delivery.
---

# Refund steps

| keeps the line breaks: the value is two lines. > folds them into spaces: the value is one sentence. Use | for steps and > for a long description.

Traps That Change Your Data

The worst YAML mistakes give no error. The file parses, and the data is quietly different from what you wrote.

No error, wrong data

---
title: Refunds #1 priority
version: 1.10
zip: 012
---

# Refunds #1 priority

Open the Outline tab and compare it with what you typed.

• title is just Refunds. In YAML, a space and # start a comment, and the rest of the line is thrown away.
• version is the number 1.1. As a number, 1.10 and 1.1 are the same, so the zero is lost.
• zip is the number 12. The leading zero is gone.

The fix for all three is quotes: "Refunds #1 priority", "1.10", "012". Add them and watch the values change.

There is one more trap. Some older YAML tools turn yes, no, on and off into true or false. The country code NO, for Norway, can become false. The parser in this course follows the newer YAML 1.2 rules and keeps them as text, but you cannot be sure every tool does. Quote them.

Frontmatter and AI Tools

Frontmatter matters even more for AI tools than for docs sites, because a tool may decide whether to read the file at all from its frontmatter alone.

A SKILL.md file, which you will write in Chapter 3, starts like this:

The frontmatter of a skill

---
name: refund-check
description: Checks a refund request against the refund policy. Use when a customer asks for a refund or a refund is late.
---

# Refund check

1. Find the order.
2. Check the refund window.
3. Check the amount limit.

An AI tool reads only the name and description of every skill at first. It loads the rest of the file only when the description matches the task. A broken frontmatter block means the skill is never found. A vague description means it is never chosen.

So the rules in this lesson are not just about tidy pages. A missing quote can switch off an agent's skill.

Where Frontmatter Is Used

• Docs sites: title, description, sidebar order, tags.
• Blogs: author, date, cover image.
• AI agent files: SKILL.md names and descriptions, subagent settings.
• Specs and plans: status, owner, ticket number.
• Static site generators: Jekyll, Hugo, Astro and many more read it on every page.

Common mistakes

Quick Check

Exercises

What to Remember

• Frontmatter is data about a file, in YAML, between two --- lines at the very top.
• Each line is key: value, with a space after the colon.
• Quote values that contain : or #, start with a special character, or must stay text.
• Indent groups and lists with spaces, never tabs. Line up keys at the same level.
• Lists: [a, b] or lines starting with - . Long text: | keeps lines, > folds them.
• Silent traps: # starts a comment, and numbers lose their zeros.
• AI tools read frontmatter to decide whether to use a file. A broken block makes a skill invisible.

Further Reading

• YAML 1.2 specification: the full format, if you ever need it.
• Learn YAML in Y minutes: a short tour of every YAML form.
• Jekyll: front matter: how one popular site generator uses it.

Next: AGENTS.md Files, where you write the file AI coding agents read at the start of every session, and prune it to only what the code cannot say.