--- title: Quoting strings, dates and lists in YAML front matter slug: yaml-front-matter-quoting excerpt: When to quote values in Markdown front matter, how dates and lists parse, and the unquoted values that silently change type. quickAnswer: Quote a string value in YAML front matter 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. An unquoted value can turn into a boolean, a number or a date, or it can stop the whole block from parsing. keyTakeaways: - A colon followed by a space inside a value breaks the parse. Quote the value. - A space followed by a hash sign starts a comment and drops the rest of the line. - Unquoted yes, no, on and off can become booleans, and version numbers and leading zeros can lose digits. - Under YAML 1.1, an unquoted date in YYYY-MM-DD form becomes a date value. Pick one style per project and keep it. - In flow-style lists, a colon with a space creates a key-value pair. The block style with quotes is harder to get wrong. publishedDate: 2026-10-07 dateModified: 2026-10-07 author: Bobby Huang cluster: E role: post status: published related: - yaml-front-matter-in-markdown - yaml-front-matter-errors - front-matter-fields-status-date-owner --- 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](yaml-front-matter-in-markdown.md). 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: ```yaml title: Fix: the parser ``` Result: error, "mapping values are not allowed here." Quote it: ```yaml 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: ```yaml summary: Step #2 #notes ``` Result: `Step`. Everything after the first ` #` is gone. Quoted, the full text survives: ```yaml summary: "Step #2 #notes" ``` Some characters cannot start a plain value at all. `@` and the backtick are reserved, so this fails: ```yaml 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: ```yaml title: 'Jane Doe''s notes' ``` Result: `Jane Doe's notes`. Double quotes allow backslash escapes such as `\n` for a new line: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml tags: [draft, review] ``` ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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](yaml-front-matter-errors.md) 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](https://www.skimmark.com/).