QMD file format: document syntax

A .qmd file is text in Pandoc Markdown, with a YAML header and executable code cells. This page covers what Quarto adds.

Sources: Quarto’s documentation pages Execution Options, Inline Code, Code Cells: Jupyter, Cross-References, Callout Blocks, Diagrams, Shortcodes and the HTML format options reference.

Front matter

A YAML block between lines of ---. Keys that choose how the document is run:

Key	Meaning
`engine`	`jupyter`, `knitr` or `markdown`. Without it, a `.qmd` with an `{r}` block uses knitr, otherwise Jupyter with the kernel of the first executable block’s language.
`jupyter`, `knitr`	Also choose the engine, e.g. `jupyter: python3`.
`execute`	Document-wide defaults for the cell options such as `echo: false`.

Every other key is an option of the output format, listed in Quarto’s reference page for each format. Some from the HTML page, by its groups: Title & Author (title, subtitle, date, author, abstract), Table of Contents (toc), Numbering (number-sections), Language (lang, an IETF tag), References (bibliography, csl), Rendering (filters), Cross-References (crossref), Execution (cache, freeze). The page’s other groups are Format Options, Fonts, Colors, Layout, Code, Figures, Lightbox Figures, Tables, Links, Footnotes, Citation, Accessibility, Includes, Metadata, Website and Text Output.

Code cells

An executable cell is a fenced code block whose language is in braces, such as ```{python} or ```{r}; diagrams use ```{mermaid} and ```{dot} cells. Options go in a special comment at the top of the cell: lines starting #|, or %%| in Mermaid and //| in Graphviz cells, whose comment syntax differs:

```{python}
#| label: fig-squares
#| fig-cap: "Squares"
#| echo: false
import matplotlib.pyplot as plt
plt.plot([n * n for n in range(5)])
```

A Python cell with a cross-reference label, caption and hidden code.

Inline code is one backtick, the engine in braces and an expression: `{python} radius`, `{r} radius`, `{julia} radius` (any Jupyter kernel) or `{ojs} radius`.

Cell options

Group	Option	Values and meaning
Attributes	`label`	Unique label; with a prefix such as `fig-` it can be cross-referenced.
	`classes`	Classes for the cell’s container.
	`renderings`	Names for several outputs, e.g. `[light, dark]`.
	`tags`	Notebook cell tags.
	`id`	Notebook cell ID; `label` if absent.
Code output	`eval`	`true` (default) or `false`; knitr also a list of expression numbers.
	`echo`	`true` (default; `false` in beamer, revealjs, pptx), `false`, `fenced` (show with the fence), or (knitr) line numbers.
	`code-fold`	`true`, `false` (default), `show`.
	`code-summary`	Text shown when code is folded.
	`code-overflow`	`scroll` or `wrap`.
	`code-line-numbers`	`true`, `false`; in revealjs also highlight steps such as `1-3\|5`.
	`lst-label`, `lst-cap`	Code listing label and caption.
Cell output	`output`	`true`, `false`, `asis` (raw Markdown).
	`warning`	Include warnings.
	`error`	Include errors and carry on.
	`include`	`false` hides code and results.
	`panel`	`tabset`, `input`, `sidebar`, `fill`, `center`.
	`output-location`	revealjs: `default`, `fragment`, `slide`, `column`, `column-fragment`.
Figures	`fig-cap`, `fig-subcap`	Caption and sub-captions.
	`fig-link`, `fig-alt`	Link target; alternative text.
	`fig-align`	`default`, `left`, `right`, `center`.
	`fig-env`, `fig-pos`, `fig-scap`	LaTeX environment, position and short caption.
	`fig-width`, `fig-height`	Figure size in inches; defaults depend on the output format (e.g. 5.5 × 3.5 for PDF).
Tables	`tbl-cap`, `tbl-subcap`	Caption and sub-captions.
	`tbl-colwidths`	`auto`, `true`, `false` or percentages.
	`html-table-processing`	`none` leaves HTML tables alone.
Layout	`layout`	Array of rows of widths, e.g. `[[3,3],[1]]`; negative values are gaps.
	`layout-ncol`, `layout-nrow`	Columns or rows for several outputs.
	`layout-align`, `layout-valign`	`default`, `left`, `right`, `center`; `top`, `center`, `bottom`.
Page columns	`column`, `fig-column`, `tbl-column`	Page column for the output, figures or tables.
	`cap-location`, `fig-cap-location`, `tbl-cap-location`	`top`, `bottom`, `margin`.

These are the options on Quarto’s Jupyter cell reference; Quarto has a separate reference for knitr cells.

Cross-references

An element whose label has one of these prefixes can be referenced as @prefix-name.

Prefix	Kind	Prefix	Kind
`fig-`	Figure	`exm-`	Example
`tbl-`	Table	`exr-`	Exercise
`lst-`	Code listing	`sol-`	Solution
`eq-`	Equation	`rem-`	Remark
`sec-`	Section	`alg-`	Algorithm
`thm-`	Theorem	`nte-`	Note callout
`lem-`	Lemma	`tip-`	Tip callout
`cor-`	Corollary	`wrn-`	Warning callout
`prp-`	Proposition	`imp-`	Important callout
`cnj-`	Conjecture	`cau-`	Caution callout
`def-`	Definition

Forms: @fig-x (“Figure 1”), @Fig-x (capitalised), [Fig @fig-x] (own prefix), [-@fig-x] (number only), [@fig-a; @fig-b] (several).

Divs and callouts

Callouts are fenced divs, opened with ::: {.callout-note} and closed with :::. There are five types: .callout-note, .callout-warning, .callout-important, .callout-tip and .callout-caution.

Shortcodes

Written {{< name args >}} and replaced when rendering:

Shortcode	Inserts
`version`	The Quarto version.
`var`	A value from `_variables.yml`.
`meta`	A value from the document’s metadata.
`env`	An environment variable.
`pagebreak`	A page break in the output format.
`kbd`	A keyboard shortcut.
`video`	An embedded video.
`include`	Another `.qmd` file’s contents.
`embed`	Cells or outputs from a Jupyter notebook.
`placeholder`	A placeholder image.
`lipsum`	Placeholder text.
`contents`	Content moved from elsewhere in the document.