Skip to main content

Authoring Markdown documents in Quarto 2

Overview

Quarto 2 uses its own dialect of Markdown as its underlying document syntax. Quarto’s Markdown is largely based on Pandoc Markdown, itself an extended and slightly revised version of John Gruber’s Markdown syntax.

Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read:

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber

This document provides an introduction to Quarto’s Markdown dialect (qmd). Authors of Markdown will largely feel at home using qmd files. The biggest conceptual change in Quarto 2 is that it can detect typos and syntax errors in your documents. Unlike Markdown, some qmd files are not valid Quarto Markdown syntax and need to be fixed before your document will render. For these situations, Quarto 2 offers an error message system with rich contextual information.

Text formatting

qmd syntax Output 
*italics*, _italics_,
__bold__, **bold**,
**_bold italics_**, __*bold italics*__
 italics, italics, bold, bold, bold italics, bold italics 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`code`
 code

Headings

qmd syntax Output 
# Heading 1

Heading 1

 
## Heading 2

Heading 2

 
### Heading 3

Heading 3

 
#### Heading 4

Heading 4

 
##### Heading 5
Heading 5
 
###### Heading 6
Heading 6

Editorial marks

Editorial marks record suggested changes and comments in the document itself. Each mark has an inline form, for a few words, and a block form, for whole paragraphs, lists or code.

The inline forms wrap text in brackets, with a two-character marker after the opening bracket:

[++ inserted text], [-- deleted text],
[!! highlighted text] and [>> a comment].

inserted text, deleted text, highlighted text and a comment.

The block forms put the same marker after the opening colons of a fenced div, and apply to everything up to the closing colons:

::: --

This paragraph is marked as deleted.

So is this one.

:::

This paragraph is marked as deleted.

So is this one.

::: ++ marks inserted content, ::: !! highlighted content, and ::: >> a comment. The marker must be followed by a space or the end of the line (::: --draft is an error, not a class).

Both forms take attributes, the inline form after the closing bracket and the block form after the marker. By convention author and date record who made a change or comment, and when:

Some text [>> needs a citation]{author="Ana" date="2026-09-24"}.

::: >> {author="Ana"}

A longer comment, over several paragraphs.

:::

Word and PowerPoint output

When you render to Word (docx) or PowerPoint (pptx), including “Download as” in quarto-hub, the marks become the real thing, with no extension or filter to install:

  • In Word, [++ ] and [-- ] become tracked insertions and deletions, [!! ] a yellow highlight, and [>> ] a comment in the review pane. The block forms apply the same to every paragraph inside. author and date become the author and date Word shows; without an author, Word shows “unknown”.

  • A comment on a stretch of text is written the way importing a Word document writes it: a span around the text that ends in the comment, with any replies after it.

    A [commented range[>> Please reword this.]{author="Ann"}[>> Done.]{author="Dee"}] in a sentence.

    In Word the first comment covers the range and the replies are further comments on the same range. Word shows them as separate comments rather than as a thread.

  • A comment inside another comment is part of the outer comment’s text, not a second comment.
  • In PowerPoint there is no tracked-change markup to write to, so each mark becomes a formatted run instead: underline for insertions, strikethrough for deletions, a yellow highlight, and comments as bracketed italic red text such as [Ana: needs a citation]. Formatting inside a marked run is lost.

When you render a document in a git repository with --attribution=git, every insertion, deletion and comment that doesn’t set author or date itself gets them from git blame on its source lines. Each person who committed marks then appears as a separate author in Word’s review pane. The name defaults to the part of the committer’s email before the @; to use full names, map the emails in the document or project metadata (both name and color are required, or the entry is ignored):

attribution:
  identities:
    ana@example.com: {name: Ana Alvarez, color: "#cc0000"}

An explicit author= or date= always wins, and a highlight has no author in Word. PowerPoint output ignores authors on insertions and deletions.

Lists

Escaping syntax characters

A backslash makes any character that qmd uses for markup literal: \*, \_, \$, \{, \[, \<, \'. Quarto 2 is stricter than Pandoc about incomplete markup (a lone * is an error, not literal text), so documents written for other Markdown processors sometimes need a few of these. Migrating Markdown to Quarto 2 lists every case and its fix.

Error messages