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: Pancake recipe

A .qmd file: YAML front matter between --- lines, then Markdown with a Python chunk. Render it with quarto render pancake.qmd:

Source (.qmd)	Rendered (html)
--- 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") ```	Pancake quantities Ingredients 150 g flour 250 ml milk Batter volume Batter volume: 400 ml

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

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
toc: true	table of contents
lang: en	document language

Several formats at once — a map, not a list. A list like [html, pdf] fails at render time with ERROR: Validation of YAML front matter failed. Declare each format instead:

format:
  html: default
  pdf: default

A colon in an unquoted value must be quoted — it ends the mapping, and the render fails:

Wrong	Right
title: Pancakes: the recipe Render error: ERROR: YAMLException: bad indentation of a mapping entry	title: "Pancakes: the recipe"

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.

include: false — source and output both stay out of the document, for setup code the reader does not need to see.

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

Wrong	Right
```python print("hi") ``` Nothing executes; the source shows as a plain code block.	```{python} print("hi") ``` The engine runs it and inserts the output.

The inline form follows the same rule — see Inline code.

Options for the whole document

Set a chunk option for every chunk at once with execute: in the front matter:

---
title: "Pancake quantities"
format: html
execute:
  echo: false
---

Every chunk hides its source; the outputs still appear. A #| option on one chunk overrides the document default.

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
typst	PDF via the Typst engine bundled with Quarto
docx	Word document
revealjs	HTML slide deck
gfm	GitHub Flavored Markdown

Projects

A directory with a _quarto.yml file is a project: documents share its front matter and render as one site. Scaffold one:

quarto create-project --type website

creates index.qmd, about.qmd, styles.css and _quarto.yml. The scaffolded project file:

project:
  type: website

website:
  title: "webproj"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true

Render the whole project:

quarto render

builds the site into _site/.

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 the built site to GitHub Pages; other providers: netlify, quarto-pub, …

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