# Frontmatter Basics Course: [Markdown](https://www.devtutorials.ai/learn/markdown) · Section: Markdown for Teams Source: https://www.devtutorials.ai/learn/markdown/team-docs/frontmatter-basics > 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. ```md runnable frontmatter expect-error title="One colon too many" dialect="docs" --- 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 ```md runnable frontmatter title="Frontmatter in one block" dialect="docs" --- 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. ```md runnable frontmatter title="The smallest frontmatter" dialect="docs" --- 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 | Where | What happens to frontmatter | |---|---| | Docs sites (Docusaurus, MkDocs, Astro, Jekyll, Hugo …) | read as data and hidden from the page | | GitHub | shown as a small table at the top of the file | | Plain CommonMark | a divider line and a heading — it looks broken | | AI coding tools | read as data, to decide when and how to use the file | This is why the boxes in this lesson start on the **Docs site** flavour. Frontmatter is not part of CommonMark or GFM. It is a platform extension, as you saw in the Markdown Flavors lesson. Only use it in files that a tool will read for it. ## 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**. ```md runnable frontmatter title="Four kinds of value" dialect="docs" --- 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. ```md runnable frontmatter title="Values that need quotes" dialect="docs" --- title: "Refunds: the rules" channel: "#refunds" author: "@asha" note: "*important*" plain: Refund rules for support staff --- # Refunds: the rules ``` | Put the value in quotes when it | Example | |---|---| | contains a colon and a space `: ` | `"Refunds: the rules"` | | contains `#` after a space | `"Refunds #1"` | | starts with `#`, `@`, `*`, `&`, `!`, `[`, `{`, `>` or `\|` | `"#refunds"`, `"@asha"` | | must stay text, but looks like a number | `"2.4"`, `"0123"` | | must stay text, but looks like true or false | `"true"` | 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. If you are not sure, use double quotes. Quotes never hurt a string value. They only stop YAML from guessing. ## Lists, Groups and Long Text ### Lists A **list** is several values under one key. YAML has two ways to write one. ```md runnable frontmatter title="Two ways to write a list" dialect="docs" --- 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. ```md runnable frontmatter title="A group of keys" dialect="docs" --- 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. Never indent YAML with a tab. Many editors insert a tab when you press the Tab key. YAML rejects tabs completely. Set your editor to insert spaces in `.md` and `.yaml` files. ### Long Text For a value that runs over several lines, put `|` or `>` after the colon, then indent the text below it. ```md runnable frontmatter title="Long text, kept or folded" dialect="docs" --- 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. ```md runnable frontmatter title="No error, wrong data" dialect="docs" --- 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: ```md runnable frontmatter title="The frontmatter of a skill" dialect="docs" --- 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 | Symptom | Cause | Fix | |---|---|---| | The page shows a divider and a heading like `title: …` | The renderer does not read frontmatter, or it does not start on line 1 | Remove anything above the first `---`; use a tool that reads frontmatter | | `Nested mappings are not allowed in compact mappings` | A value contains `: ` | Put the value in double quotes | | `Tabs are not allowed as indentation` | A tab in the indent | Replace it with spaces | | `Unresolved alias` | A value starts with `*` or `&` | Put the value in double quotes | | `Plain value cannot start with reserved character @` | A value starts with `@` | Put the value in double quotes | | `Map keys must be unique` | The same key appears twice | Keep one, delete the other | | A title is cut off after a `#` | ` #` starts a comment | Put the title in quotes | | A version or code lost its zeros | YAML read it as a number | Put it in quotes | ## 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](https://yaml.org/spec/1.2.2/): the full format, if you ever need it. - [Learn YAML in Y minutes](https://learnxinyminutes.com/docs/yaml/): a short tour of every YAML form. - [Jekyll: front matter](https://jekyllrb.com/docs/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.