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 =

1. YAML front matter +
2. Markdown prose +
3. Code chunks (usually python)

Source (.qmd)	Rendered with quarto render pancake.qmd into 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

By default, the code chunks run at render time. echo: false (14) in the example hides the source code, so only the output appears in the rendered document here.

Front matter

• YAML
• wrapped between two --- lines
• always 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 causes a fatal exception:

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

Code chunks

• A fenced Markdown codeblock
• language name must be wrapped in { braces
• executed by the compile engine
• output inserted into rendered document

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

Available languages: python (via Jupyter), r (via knitr), julia, bash, and ojs.

Chunk options

Lines starting with #| at the top of the chunk modifies compile-time behaviour:

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