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.

Typst and PDF output

Typst output (format: typst) has no review pane, so the marks are drawn on the page instead: insertions are underlined in green, deletions struck through in red, highlights get a yellow background, and comments appear in a small blue box, prefixed with their author when they have one. The block forms get the same treatment, with a colored rule down their left side.

Each mark is drawn by a Typst function that you can redefine to change how it looks. The inline forms call quarto-insert, quarto-delete, quarto-highlight and quarto-edit-comment; the block forms call the same names ending in -block. Every function takes the mark’s author and date (or none) and its content as body. To redefine one, put a #let with the same name in the document’s header-includes. For example, this shows each deletion as a gray “(removed)” instead of struck-through text:

header-includes: |
  ```{=typst}
  #let quarto-delete(author: none, date: none, body) = text(fill: gray)[(removed)]
  ```

Lists

Task lists

Start a list item with [ ] or [x] (or [X]), followed by a space, to make it a task:

- [x] Write the draft
- [ ] Ask for a review
- [ ] Publish

In HTML, each task shows a checkbox in place of its bullet, and plain items in the same list keep their bullets. In an ordered list, a task keeps its number and the checkbox follows it. To hide the numbers too, set $task-list-ordered-markers: false in a custom theme.

The space after the brackets is required: - [ ] on its own is an ordinary item, while - [ ] is an empty task. The checkboxes in rendered HTML are read-only. In the preview of an editable document, clicking one toggles the item between [ ] and [x] in the source.

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