--- title: "YAML front matter in Markdown: a practical guide" slug: yaml-front-matter-in-markdown excerpt: Markdown front matter is the YAML block at the top of a file that holds fields like status, date and owner. Here is how it works, which tools read it, and why it sometimes shows up as plain text. quickAnswer: Front matter in Markdown is a block of metadata at the very top of a file, set between two lines of three dashes. It is usually written in YAML as simple key and value pairs, such as a status, a date and an owner. It is not part of core Markdown. Tools that support it read the block as data and hide it from the rendered page. Tools that do not support it show the block as ordinary text, often as a heading. keyTakeaways: - Front matter is a YAML block between two lines of three dashes, and most tools expect the first dash line to be the first line of the file. - It is a convention, not part of core Markdown, so some viewers render it as plain text. - YAML 1.1 and YAML 1.2 parsers can read the same header differently, mainly for words like yes and no, dates and numbers. - Most invalid headers come from a few causes, such as a colon inside a value, tabs, or a missing closing line. - When in doubt, quote the value. A quoted string means the same thing to every parser. publishedDate: 2026-10-06 dateModified: 2026-10-06 author: Bobby Huang cluster: E role: pillar status: published faq: - q: Is front matter part of the Markdown standard? a: No. CommonMark and the original Markdown description do not define it. It is a convention that static site generators, Markdown editors and many libraries support. A plain Markdown renderer treats the block as normal text. - q: Does front matter have to be YAML? a: YAML is the most common format. Some tools also accept TOML between two lines of three plus signs, or JSON. Check what your tool reads before you switch. - q: Why does my front matter show up as a heading? a: Your viewer does not support front matter. In CommonMark, a line of three dashes right under a paragraph turns that paragraph into a level 2 heading. So the fields above the closing line often run together as one large heading. related: - yaml-front-matter-errors - what-is-an-agent-handoff-file - how-to-review-markdown-your-ai-agents-write --- If your AI coding agents write Markdown, most of their files probably start the same way. A short block of fields sits between two dash lines at the top: a status, a date, an owner, maybe a list of tags. That block is front matter. You read it first, and you fix it when it breaks. This guide covers what Markdown front matter is, the YAML rules that matter, which tools read it, and why it sometimes shows up as plain text. For a list of specific errors and fixes, see [common YAML front matter errors](yaml-front-matter-errors.md). ## What front matter is Front matter is metadata about a file, kept inside the file. Here is a header an agent might write on a handoff: ```yaml --- title: Settings page dark theme status: blocked date: 2026-10-06 owner: Jane Doe tags: - ui - settings --- ``` Everything between the two `---` lines is YAML. Each line is a key, a colon, a space and a value. The `tags` key holds a list, one item per line, each starting with a dash. Below the closing `---` comes the normal Markdown body. A tool that understands front matter reads the block as data and leaves it off the rendered page. That is how a blog engine knows a post's title and date, and how a Markdown editor shows a file's properties. ## Why agents write YAML headers Agents add front matter because it makes files easy to sort and check without reading the body. A [handoff file](what-is-an-agent-handoff-file.md) with `status: blocked` and an owner tells you in seconds whether it needs you. Scripts can also read the same fields to build an index of open work. The catch is that YAML is stricter than it looks. An agent can write a header that looks fine to you and still fails to parse. Or it parses, but a value means something other than what the agent intended. ## The rules that matter You do not need the whole YAML spec. These rules cover most headers: 1. **Put the opening `---` on the first line.** Most tools, Jekyll among them, only look for front matter at the very top. A blank line, a heading or a comment above it means the block is not front matter to those tools. Pandoc is an exception: it also accepts a metadata block later in the file. 2. **Close the block with `---`.** Without a closing line, the tool cannot tell where the data ends and the body begins. Pandoc also accepts three dots (`...`) as the closing line, but `---` works in more places. 3. **A key is followed by a colon and a space.** `status: done` is a key and a value. `status:done` is not. 4. **Indent with spaces, never tabs.** The YAML spec does not allow tabs for indentation. 5. **Quote values with special characters.** A value that contains a colon followed by a space, or a space followed by `#`, or that starts with characters like `[`, `{`, `*`, `&` or `@`, needs quotes. > Quoting is the safe default. `title: "Fix: login loop"` parses the same way everywhere. Without the quotes, it fails. ## YAML 1.1 vs YAML 1.2 There are two YAML versions in common use, and parsers do not all follow the same one. The differences show up in values that look like plain words or numbers. - **Yes and no.** Under YAML 1.1, unquoted `yes`, `no`, `on` and `off` are booleans. Under YAML 1.2, only `true` and `false` are. So `approved: no` may be the boolean false in one tool and the text "no" in another. A country code like `NO` hits the same rule. - **Dates.** YAML 1.1 has a timestamp type, so parsers that follow it may turn an unquoted `2026-10-06` into a date object. Others keep it as text. If a script compares dates as strings, quote them. - **Numbers.** An unquoted `1.10` is a number and becomes 1.1. An id like `0042` loses its leading zeros, and a YAML 1.1 parser may read it as an octal number. Quote ids and version strings. If a header has to mean the same thing to every tool, quote anything that is meant as text. ## Which tools read front matter Front matter is a convention, so support varies. Static site generators such as Jekyll and Hugo read it to get each page's title, date and layout. Hugo also accepts TOML and JSON front matter. Pandoc reads a YAML metadata block for the title, author and date of a document. Libraries in most languages can split a file into its front matter and its body. A plain Markdown renderer does none of this. It sees dashes and text. ## Why does my front matter show as text? If the header appears on the rendered page, one of three things is going on: 1. **The viewer does not support front matter.** In CommonMark, the opening `---` becomes a horizontal rule. The closing `---` sits right under the fields, and a dash line under a paragraph turns that paragraph into a level 2 heading. You often get a line, then your fields run together as one large heading. 2. **The block is not on the first line.** A blank line or any text above the opening `---` means most tools treat it as ordinary Markdown. 3. **The closing line is missing or wrong.** Four dashes, a trailing word, or no closing line at all can stop a tool from finding the end of the block. Check the second and third causes first. They are quick to fix in the file itself. If both look right, the viewer is the issue. ## How to fix invalid front matter When a tool reports a YAML error, the line number usually points at or just after the problem. Look for a colon inside a value, a tab, an unclosed quote, or a list item that is indented differently from its neighbors. Quote the value or fix the spacing, then parse again. The companion guide walks through each of these with a broken example and a fixed one: [common YAML front matter errors and how to fix them](yaml-front-matter-errors.md). > Ask your agent to quote every string value in its headers. It costs a few characters and removes most of the guesswork. ## Where Skimmark fits Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. Planned for v1: a Frontmatter Table that shows the YAML header as key and value rows instead of raw text, so you can scan a status, date and owner at a glance. The app itself has no AI features. To see what Skimmark is and follow along, visit [skimmark.com](https://www.skimmark.com/).