YAML front matter in Markdown

To add front matter to a Markdown file, put a block of metadata at the very top between two lines of three hyphens (---), written as YAML key-value pairs such as title: and date:. A tool reads these fields before the body content and strips the block from the output. Front matter is not part of CommonMark; it is a convention from static site generators and document processors.

YAML front matter in Markdown syntax reference

YAML front matter in Markdown key facts

• Front matter goes at the very top of the file, with no blank line or content before the opening fence.
• The common form is YAML between two lines of three hyphens (---), with one key: value pair per line.
• Values can be strings, numbers, dates, lists such as [a, b, c], and nested objects.
• Front matter is not in CommonMark, original Markdown, or the formal GitHub Flavored Markdown spec: support depends on the tool.
• Jekyll, Hugo, Pandoc, and Obsidian read front matter; Hugo also accepts TOML (+++) and JSON variants.
• A tool that supports front matter removes the block before rendering, while one that does not may show the --- as a horizontal rule.

Treat front matter as application data

Front matter is not part of core Markdown. A static-site generator, note app, or publishing pipeline reads the metadata before it sends the remaining document to a Markdown parser. That means field names and accepted values come from the application, not from Markdown itself.

Quote dates and values that YAML might interpret unexpectedly, keep indentation consistent, and avoid tabs. Do not place a blank line before the opening ---; many tools require the delimiter to be the first line. Because the same delimiter can also create a horizontal rule or Setext heading, front matter is only recognised when the host application explicitly enables it.

Basic syntax

Put three hyphens on the first line of the file, add YAML key-value pairs, then close with another line of three hyphens. The body of the document begins after the closing fence.

Markdown

---
title: Getting started
date: 2026-07-04
tags: [markdown, docs]
---

# Getting started

The body of the document begins here.

Rendered output

HTML output

<h1>Getting started</h1>
<p>The body of the document begins here.</p>

The front matter itself does not appear in the rendered body. A tool that understands front matter reads the fields and strips the block, so only the content after the closing --- becomes HTML. A renderer that does not understand front matter may instead display the --- as a horizontal rule or heading, covered below.

YAML front matter fields

YAML front matter can hold strings, numbers, dates, lists, and nested objects. Keys are separated from values by a colon and a space.

Markdown

---
title: Release notes
author: Markdific
draft: false
version: 2.1
keywords:
  - markdown
  - release
  - notes
seo:
  canonical: https://example.com/notes
  robots: index, follow
---

Lists can be written inline as [a, b, c] or as indented - items. Nested objects, such as the seo block above, group related fields. String values with special characters should be quoted.

TOML and JSON front matter

Some tools accept front matter in formats other than YAML. TOML front matter is fenced with +++ instead of ---, a convention popularized by the Hugo static site generator. JSON front matter is also supported in some tools.

TOML front matter

+++
title = "Getting started"
date = 2026-07-04
tags = ["markdown", "docs"]
+++

JSON front matter

{
  "title": "Getting started",
  "date": "2026-07-04",
  "tags": ["markdown", "docs"]
}

Support for TOML and JSON varies by tool. YAML with --- fences is the most widely recognized format, so prefer it unless your generator specifically calls for another.

Placement rules

Most tools that support front matter expect it to start on the first line, with no blank line or content before the opening fence. A document normally has one metadata block at the top, but the exact rules belong to the publishing application rather than Markdown itself.

Markdown (correct)

---
title: Correct placement
---

# Body

Markdown (incorrect: blank line before the fence)

---
title: Not detected as front matter
---

In the incorrect example, the leading blank line means many parsers no longer treat the block as front matter. The --- may then render as a horizontal rule instead.

Flavor differences

Front matter is not defined by the original Markdown or the CommonMark specification. It is a convention that individual tools and extensions implement. Support therefore depends on the processor, not the flavor label alone.

Front matter became common through static site generators such as Jekyll, which reads a leading YAML block to set page variables. Pandoc supports a native YAML metadata block delimited by --- and closed by --- or ..., and enables it in relevant reader modes.

MultiMarkdown has its own top-of-file Key: value metadata block and can accept YAML-style fences. CommonMark and classic Markdown Extra do not define front matter. In a bare CommonMark renderer, a leading --- block is ordinary Markdown and may be interpreted as a thematic break or Setext heading.

Other platforms (Obsidian, Hugo)

• Obsidian: reads YAML front matter as note properties, using fields such as tags, aliases, and cssclasses, and hides the block in reading view.
• Hugo: accepts YAML (---), TOML (+++), and JSON front matter, and uses the fence style to detect the format.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific treats a leading --- block as document front matter rather than body content. Front matter is a convention added on top of standard Markdown, so its exact handling depends on the renderer.

Because front matter behavior differs across tools, a document that must render cleanly everywhere should account for renderers that do not recognize the block. Formats such as TOML +++ and JSON front matter are non-standard and may not be recognized unless the renderer supports them.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Content before the fence. Front matter must be the first thing in the file. A blank line or any text above the opening --- stops most tools from detecting it.
• Missing closing fence. Without a second --- (or ... in Pandoc), the block is not closed and can swallow part of the document.
• Invalid YAML. A missing space after a colon, bad indentation, or an unquoted special character breaks parsing. Quote values that contain colons or symbols.
• Expecting universal support. A leading --- block renders as content on a bare CommonMark renderer, often as a horizontal rule followed by a heading.
• Mixing fence styles. Use --- for YAML and +++ for TOML consistently. Mixing them confuses the parser about the format.
• Tabs in YAML. YAML forbids tabs for indentation. Use spaces.

Best practices

• Put front matter at the very top with no blank line or content before it.
• Prefer YAML with --- fences, the most widely recognized format.
• Always close the block, with ---, or ... where Pandoc allows it.
• Quote string values that contain colons, hashes, or other special characters.
• Keep only fields your tool actually reads, so the metadata stays meaningful.
• If a document must render everywhere, remember that renderers without front matter support will show the block, so plan accordingly.

HTML equivalent

Front matter has no direct HTML equivalent. A tool that supports it reads the fields, often mapping them to <meta> tags or page variables, and removes the block before rendering. Only the body after the closing fence becomes HTML.

Markdown

---
title: Sample
description: A short description
---

# Sample

Body text.

HTML output

<!-- Front matter is consumed by the tool, not rendered as body content. -->
<!-- A generator may emit meta tags from the fields, for example: -->
<title>Sample</title>
<meta name="description" content="A short description">
<h1>Sample</h1>
<p>Body text.</p>

FAQ

What is front matter in Markdown? Front matter is a metadata block at the top of a Markdown file, usually YAML between two lines of three hyphens. It holds fields such as title, date, and tags that a tool reads before the body content.

Is front matter part of standard Markdown? No. Front matter is not in the original Markdown or the CommonMark specification. It is a convention from static site generators, MultiMarkdown metadata, and Pandoc's YAML metadata block.

Does Pandoc support front matter? Yes. Pandoc has a native YAML metadata block delimited by three hyphens at the top and closed by three hyphens or three dots, and it enables the block by default in its gfm and commonmark_x modes.

What is the difference between YAML and TOML front matter? YAML front matter uses --- fences and colon-separated key-value pairs. TOML front matter uses +++ fences and equals-sign assignments. The fence style tells a tool which format to parse.

Why does my front matter show as a horizontal line? The renderer does not support front matter, so it reads the opening --- as a horizontal rule. Use a tool that recognizes front matter, or remove the block if the renderer will not consume it.

Where does front matter go in the file? Put it at the top of the file. Most supporting tools require the opening fence on the first line and expect one metadata block, but confirm the rules of the application that reads it.

Does GitHub render front matter? GitHub does not treat it as part of the formal spec, but it hides a leading YAML block on rendered Markdown files and displays it as a table in some views rather than as body text.

What fields go in Markdown front matter? There is no fixed list, since each tool reads its own fields. Common ones are title, date, author, tags, description, draft, and slug. Keep only the fields your generator or processor actually uses, so the metadata stays meaningful.

How do you write a list value in YAML front matter? Write it inline in square brackets, such as tags: [markdown, docs], or as indented - items on separate lines under the key. Both produce the same list, so pick whichever is easier to read.

Does Obsidian use front matter? Yes. Obsidian reads YAML front matter as note properties, using fields such as tags, aliases, and cssclasses, and hides the block in reading view.

Can you use front matter in a plain Markdown file without a static site generator? Yes, but only a tool that understands front matter will consume it. Pandoc and note apps like Obsidian read it, while a bare CommonMark renderer treats a leading --- block as body content, often as a horizontal rule followed by a heading.

Sources and compatibility references

• YAML 1.2.2 specification
• Pandoc User's Guide

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Horizontal rules
• Headings in Markdown
• Inline HTML in Markdown
• Markdown flavors compared