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

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

Several formats at once — a map, not a list. A list fails at render time:

Wrong	Right
format: [html, pdf] Render error: ERROR: Validation of YAML front matter failed	format: html: default pdf: default Renders pancake.html and pancake.pdf.

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):

Source (in the .qmd)	Rendered document
flour = 150 milk = 250 print(f"Batter volume: {flour + milk} ml")	flour = 150 milk = 250 print(f"Batter volume: {flour + milk} ml") Batter volume: 400 ml

With echo: false:

Source (in the .qmd)	Rendered document
#| echo: false flour = 150 milk = 250 print(f"Batter volume: {flour + milk} ml")	Batter volume: 400 ml

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

Source (in the .qmd)	Rendered document
#| eval: false print("Batter volume: 400 ml")	print("Batter volume: 400 ml") No output — the code never ran.

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

Source (in the .qmd)	Rendered document
#| include: false print("Batter volume: 400 ml")	Nothing — neither the source nor the output appears.

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; the table is @tbl-pan and the figure is @fig-batter.

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

: Pancake ingredients {#tbl-pan}

```{python}
#| label: fig-batter
#| fig-cap: "Batter volume"
import matplotlib.pyplot as plt
plt.bar(["flour", "milk"], [150, 250])
plt.show()
```

The references render as "Section 1", "Table 1" and "Figure 1"; the table caption becomes "Table 1: Pancake ingredients" and the figure caption "Figure 1: Batter volume". Quarto numbers each target by the order it appears in the document.

Projects

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

my-site/
├── _quarto.yml   # project config: type, site settings, formats
├── index.qmd     # home page
├── about.qmd     # second page
├── styles.css    # custom styles for the html format
└── _site/        # built site (generated by quarto render)

Scaffold one:

quarto create-project --type website

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

project:
  type: website              # website, book, default, manuscript

website:
  title: "My site"           # shown in the browser tab and navbar
  navbar:
    left:                    # links on the left of the navigation bar
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo                # Bootstrap theme
      - brand                # brand color palette
    css: styles.css          # extra stylesheet
    toc: true                # table of contents on each page

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