Quoting strings, dates and lists in YAML front matter

Front matter is the YAML block between two --- lines at the top of a Markdown file. Most of the time you can type values without quotes and they work. The trouble is the other times. An unquoted value can turn into a boolean, a number or a date, or it can stop the whole block from parsing.

If you are new to front matter, start with YAML front matter in Markdown: a practical guide. This post covers one narrow job: when to quote, and how to write dates and lists so they parse the way you meant.

The short rule

Quote a string value when it contains a colon followed by a space, starts with a special character, or could be read as something other than text. If you are unsure, quote it. Quotes around plain text never hurt.

Colons, hashes and leading symbols

A colon followed by a space tells YAML a new key is starting. In a title, that breaks the parse:

title: Fix: the parser

Result: error, "mapping values are not allowed here." Quote it:

title: "Fix: the parser"

Result: Fix: the parser.

A space followed by # starts a comment. The parser does not warn you. It just drops the rest of the line:

summary: Step #2 #notes

Result: Step. Everything after the first # is gone. Quoted, the full text survives:

summary: "Step #2 #notes"

Some characters cannot start a plain value at all. @ and the backtick are reserved, so this fails:

owner: @jane-doe

Result: error. Write owner: "@jane-doe" instead. Values that start with *, &, !, [, {, | or > also mean something special to YAML. Quote them.

Single quotes or double quotes

Both work. They differ in escapes.

Single quotes are literal. Their one escape is a doubled single quote:

title: 'Jane Doe''s notes'

Result: Jane Doe's notes.

Double quotes allow backslash escapes such as \n for a new line:

title: "Line one\nLine two"

Result: two lines of text. If your values contain backslashes, such as Windows paths, single quotes are the safer choice because nothing gets escaped by accident.

Values that change type

This is the quiet failure. The file parses, but the value is not what you wrote.

Yes and no. In YAML 1.1, which many front matter tools still follow, yes, no, on and off are booleans:

draft: no
reviewed: yes

Result: draft: False, reviewed: True. That can be fine for a flag. It is wrong for a country code like NO or a status of no. Quote those:

draft: "no"
country: "NO"

Result: the strings no and NO. YAML 1.2 dropped yes/no/on/off as booleans, but you rarely know which version a given tool uses. Quoting works under both.

Version numbers. An unquoted 1.10 is a float:

version: 1.10

Result: 1.1. The trailing zero is gone. Write version: "1.10".

Leading zeros. ZIP codes and IDs with a leading zero are numbers to YAML:

zip: 01234

Result under YAML 1.1: 668, because a leading zero means octal. A YAML 1.2 parser reads it as 1234. Both lose the zero. Write zip: "01234".

Dates

Under YAML 1.1, an unquoted date in YYYY-MM-DD form becomes a date value, not a string:

date: 2026-10-06

Result under YAML 1.1: a date object for October 6, 2026. A YAML 1.2 parser that uses the core schema keeps it as the string 2026-10-06. Static site generators often want exactly this, so leave it unquoted if your tool sorts or formats by date.

Two cautions. First, the format must be exact. One missing zero and you get plain text:

date: 2026-10-6

Result: the string 2026-10-6, not a date. Nothing errors, so sorting just breaks later. Second, if a tool expects text and chokes on a date object, quote it:

date: "2026-10-06"

Result: the string 2026-10-06. Pick one style per project and keep it.

Lists

YAML has two list styles. Both give the same result here:

tags: [draft, review]

tags:
  - draft
  - review

Result for both: ['draft', 'review'].

The flow style (square brackets) has a trap. A colon with a space inside it creates a key-value pair instead of a string:

tags: [draft, needs: review]

Result: ['draft', {'needs': 'review'}]. The second tag is now a small map, not text. The block style with quotes is easier to read and harder to get wrong:

tags:
  - "needs: review"
  - "#urgent"

Result: ['needs: review', '#urgent']. Note that #urgent must be quoted, or the line is a comment.

For an empty list or empty string, be explicit:

tags: []
owner: ""

Result: an empty list and an empty string. A bare owner: with no value parses as null, which some tools treat differently from an empty string.

A full example

Here is a front matter block that uses each rule above:

title: "Q4 plan: draft 2"
date: 2026-10-06
status: "no"
owner: Jane Doe
tags:
  - planning
  - "needs: review"
version: "1.10"

Result: the title keeps its colon, the date is a real date under YAML 1.1, status is the string no, and version stays 1.10.

When the parse still fails

If a block still will not load, the cause is usually indentation, tabs, or a missing closing ---. Common YAML front matter errors and how to fix them walks through each one.

Reading front matter without squinting at YAML

If agents write front matter into your files every day, raw YAML is slow to scan. Skimmark is a Markdown reader in development, and its Frontmatter Table, which shows the YAML header as key/value rows, is planned for v1. Until then, the rules above will keep your values what you meant them to be.

To see what Skimmark is and follow along, visit skimmark.com.