Cheatsheets:Quarto

Quick reference for smart people — part of our dev cheatsheets collection.

Quarto is a scientific and technical publishing system: Markdown content, YAML front matter and executable code chunks that render to HTML, PDF, Word and more. It builds on Pandoc.

Quarto uses Markdown for prose content. If you are unfamiliar with Markdown syntax, see Cheatsheets:markdown.

New to Quarto? You may find this Get Started tutorial interesting.

Basic example

A .qmd file: front matter between --- lines, then Markdown with a Python chunk:

---
title: "Pancake quantities"
format: html
---

## Ingredients

- 150 g flour
- 250 ml milk

## Batter volume

```{python}
# | echo: false
flour = 150
milk = 250
print(f"Batter volume: {flour + milk} ml")
```

Render it:

quarto render pancake.qmd

The chunk runs at render time; with echo: false the source stays hidden and only the output appears in the document:

Ingredients

• 150 g flour
• 250 ml milk

Batter volume

Batter volume: 400 ml

Front matter

YAML between --- lines at the top of the file:

---
title: "Pancake quantities"
author: "Ada"
date: today
format: html
toc: true
---

Key	Effect
title: "Pancakes"	document title
author: Ada	author; a list of authors: [Ada, Bo]
date: today	date; the magic value today becomes the current date at render time
format: html	output format; several at once: [html, pdf]
toc: true	table of contents
lang: en	document language

Code chunks

A fenced block whose info string names a language in braces runs as code; the engine executes it and inserts the output:

```{python}
print("hi")
```

Engines include python (via Jupyter), r (via knitr), julia, bash and ojs.

Chunk options — lines starting with #| at the top of the chunk configure it:

Option	Effect	Example
echo	show the source (default true)	#| echo: false
eval	run the code (default true)	#| eval: false
include	keep source and output in the document (default true)	#| include: false
label	chunk label, referenced with @label	#| label: fig-batter
fig-cap	caption for figure output	#| fig-cap: "Batter volume"

echo — without it source and output both appear; with echo: false only the output:

Without (default)	With echo: false
flour = 150 milk = 250 print(f"Batter volume: {flour + milk} ml") Output: Batter volume: 400 ml	# | echo: false flour = 150 milk = 250 print(f"Batter volume: {flour + milk} ml") Output: Batter volume: 400 ml

eval: false — the source is shown but nothing runs, handy for scratch code you want to keep visible.

Inline code

Inline code executes when the language is named in braces:

Source	Renders as
`{python} flour + milk`	400
`flour + milk`	flour + milk (literal, not evaluated)

Cross-references

Give a section, table or figure an identifier, then refer to it with @:

## Recipe data {#sec-data}

The amounts live in @sec-data; see Table @tbl-pan.

| Ingredient | Amount |
|---|---|
| Flour | 150 g |

: Pancake ingredients {#tbl-pan}

The reference @sec-data renders as "Section 1", the table caption becomes "Table 1: Pancake ingredients", and figures are referenced the same way with @fig-label.

Formats

The format key picks the output. HTML and PDF work out of the box:

format	output
html	standalone HTML page
pdf	PDF, via LaTeX or the Typst engine
typst	PDF via the Typst engine bundled with Quarto
docx	Word document
revealjs	HTML slide deck
gfm	GitHub Flavored Markdown

CLI

Command	What it does
quarto render file.qmd	render one file, or a whole project
quarto render file.qmd --to pdf	override the output format
quarto preview	live-render preview while editing
quarto create-project --type website	scaffold a project (default, book, website, manuscript)
quarto publish gh-pages	publish to GitHub Pages, Netlify or Quarto Pub

Gotcha: a fence without braces is a static code block — it never runs. A chunk that "does nothing" is usually this:

```python
print("hi")
```

Fix: put the language in braces, then it executes:

```{python}
print("hi")
```

The inline form follows the same rule: `{python} flour + milk` renders as 400, while `flour + milk` renders the literal text flour + milk.

Gotcha: YAML values containing a colon must be quoted. Unquoted:

title: Pancakes: the recipe

fails at render time with

ERROR: YAMLException: bad indentation of a mapping entry

Fix: quote the value:

title: "Pancakes: the recipe"

Further reading

• Quarto documentation — the official docs
• Get Started tutorial — the recommended tutorial
• Cheatsheets:markdown — Markdown syntax used by Quarto
• Pandoc — the document converter Quarto builds on