Skip to main content

Failed to parse metadata value as markdown

yaml
Quarto tried to parse a metadata value as markdown and could not. The value will be treated as a plain string.

Q-1-20 — Failed to parse metadata value as markdown

Quarto tried to parse a metadata value as markdown and could not. The value will be treated as a plain string.

What this means

Quarto 2 parses string-valued YAML metadata as markdown by default, so that markup like *emphasis* and [links](./other.qmd) inside fields such as title: or subtitle: renders correctly downstream. This error fires when the markdown parser cannot make sense of the value.

The error comes in two flavors:

  • Warning when the value carries no explicit tag and the markdown parse fails: Quarto falls back to treating the value as a plain string and continues.
  • Error when the value is explicitly tagged !md (forcing markdown interpretation) and the markdown parse fails: Quarto cannot honor the tag, so it rejects the value.

Why this happens

Most often, a metadata string that looks ordinary contains characters the markdown parser interprets as syntax:

  • A value with unbalanced square brackets, parentheses, or asterisks looks like an incomplete link or emphasis run.
  • A value beginning with # looks like a heading.
  • Pipe characters or backticks can look like table or code syntax.

How to fix

For values you want to keep as plain strings, add the !str tag:

title: !str "Q-1-20: a markdown puzzle"

The !str tag tells Quarto to skip markdown parsing for this value, so any of the characters above pass through unchanged.

A few presentation keys are always rendered as markdown, even when tagged !str: toc-title, the website, navbar, and sidebar titles, and page footer text. For these, fix the markdown instead.

For values you genuinely want to render as markdown, fix the markdown so that it parses. The message includes the underlying markdown parser’s diagnostic — the same error the text would produce in a document body, with spans pointing into your YAML file — so it shows exactly which part of the value failed to parse, and why.

If the value is explicitly tagged !md and you do not actually need markdown interpretation, remove the tag.