Add YAML quoting guidance for keywords with spaces in MANUAL.txt

[marekkowalczyk]

Description

The Pandoc MANUAL.txt lacks clear guidance on properly escaping keywords containing spaces in YAML frontmatter, specifically for the keywords field. This may lead to parsing errors for users when keywords like "bug fix" or "user interface" are used without quotes.

Affected locations

Line 2794 (general keywords description):

pandoc/MANUAL.txt

Line 2794 in 15ddf41

`keywords`

text
`keywords`
:   list of keywords to be included in HTML, PDF, ODT, pptx, docx
    and AsciiDoc metadata; repeat as for `author`, above

Missing: Mention that keywords with spaces require double quotes in flow style.

Lines 5111+ (YAML examples section), especially line 5124:

pandoc/MANUAL.txt

Line 5124 in 15ddf41

keywords: [nothing, nothingness]

keywords: [nothing, nothingness]

Missing: Example showing quoted keywords with spaces.

Suggested fix

At line 2794, update to:

`keywords`
:   list of keywords to be included in HTML, PDF, ODT, pptx, docx
    and AsciiDoc metadata; repeat as for `author`, above.
    Keywords with spaces must be quoted: `keywords: ["bug fix", "user interface"]`.

In the YAML examples section (around line 5124), add:

keywords: [nothing, nothingness, "bug fix", "user interface"]

Why this matters

Unquoted keywords with spaces (keywords: [bug fix, user interface]) cause YAML parsing failures

Flow style [] is commonly used for brevity, but requires proper quoting

Current examples may imply unquoted spaces work, which may be incorrect.

[tarleb]

Thanks for the report. This is one of the (many) pitfalls of YAML. I'm not sure if those should be discussed in the pandoc manual, but if we do, then we'd have to limit the warning to this specific syntax. Values with spaces don't have to be quoted if this multi-line syntax is used:

keywords:
  - nothing
  - nothingness
  - bug fix
  - user interface

[marekkowalczyk]

Thanks for the quick reply and for acknowledging YAML's pitfalls — that validation alone is really helpful.

Given how frequently these kinds of YAML gotchas come up (quoting rules, implicit typing, whitespace sensitivity, etc.), and considering that the broader Markdown/static-site ecosystem has largely standardized on offering YAML + TOML + JSON frontmatter (most notably Hugo, but also remark-frontmatter, Eleventy, Zettlr, etc.), would it be feasible for Pandoc to add native support for TOML (via +++ delimiters) and/or JSON (via { … } blocks) in addition to the existing YAML (---)?

This would be fully backward-compatible, would parse into the same Meta structure, and would make content far more portable across tools without forcing users into awkward workarounds or conversions.

I've opened a detailed enhancement request here that revisits the old discussions (#2425, #10295) with current context and addresses the concerns raised back then:

#11525

I'd really value your thoughts on whether this feels like a worthwhile direction in 2026 — especially now that TOML is very mature, Haskell parsers are solid, and JSON is already half-supported in Pandoc's ecosystem. Happy to iterate on the proposal if there's interest.

Thanks again!

[jonassmedegaard]

Support for TOML in tracked in issue #11525.
I suggest to limit this issue to the stated topic: Documenting limits of YAML.

[marekkowalczyk]

Support for TOML in tracked in issue #11525. I suggest to limit this issue to the stated topic: Documenting limits of YAML.

Fair point — let's keep this focused on documenting YAML.

@tarleb, regarding your note that block-style lists don't need quoting for values with spaces: would a minimal addition to the manual be welcome? For example, a sentence near the keywords field noting that flow-style values with spaces require quotes, plus a brief example. Happy to draft a PR if that's the preferred way to move forward.

[jgm]

My own preference is not to clutter up the manual with details on YAML syntax. We already link to documentation for YAML syntax.

Unquoted keywords with spaces (keywords: [bug fix, user interface]) cause YAML parsing failures

No, they don't. This works fine:

% pandoc -t native -s
---
keywords: [nothing, nothingness, bug fix, user interface]
...
^D
Pandoc
  Meta
    { unMeta =
        fromList
          [ ( "keywords"
            , MetaList
                [ MetaInlines [ Str "nothing" ]
                , MetaInlines [ Str "nothingness" ]
                , MetaInlines [ Str "bug" , Space , Str "fix" ]
                , MetaInlines [ Str "user" , Space , Str "interface" ]
                ]
            )
          ]
    }
  []

Hence, inclined to close this.

[marekkowalczyk]

@jgm You're right — I tested against the YAML spec assumption rather than against Pandoc's actual behavior. Thanks for checking.

Closing this.

[bpj]

In Pandoc metadata you will always be ok if you use single quotes (which you escape by doubling: 'don''t') or a block scalar when in doubt. Since Pandoc parses values as Markdown you can use HTML entities inside single quotes rather than fighting with YAML doublequoted string escapes.