Quarto Basics

Overview

Quarto is a publishing system used to create documents in a wide variety of formats including HTML, PDF, Office (docx and pptx), OpenOffice, JATS, and many more.

You author these documents using markdown, an easy to write plain-text format. You then optionally add code (e.g. Python, R, JavaScript, etc.) to the documents to dynamically create figures, tables, etc. and then render the documents to their final format using Quarto.

Hello, Quarto

Here’s a simple example of a markdown document that includes a cross-referenced figure generated by Matplotlib:

---
title: "Matplotlib Demo"
author: "Norah Smith"
date: "May 22nd, 2021"
format: 
  html:
    code-fold: true
jupyter: python3
---

## Polar Axis

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

Here’s what the document looks like when rendered by Quarto:

This is an example of a Quarto document with one section containing one data visualization. At the top of the document in larger text is the title ('Matplotlib Demo'). On the following line in normal-sized text is the author (Norah Smith), and underneath that is the document date (May 22, 2021). Underneath that in large text is the section title, 'Polar Axis'. Afterwards, there is a line of text: 'For a demonstration of a line plot on a polar axis, see fig.1'. Under that is a triangle pointing at the word 'Code', indicating a code-fold button. Below this is a plot of a straight line in polar coordinates. There is a large black circle containing 4 smaller concentric gray circles with 4 axes overlaid on it. Angle measurements are indicated on the largest outer circle, starting at 0 degrees on the right side of the circle and continuing around the circle in 45 degree increments; 90 degrees is labeled at the top of the circle, 180 degrees is labeled at the left of the circle, and 270 degrees is labeled at the bottom of the circle. There are four axes on this circle, each of which are straight lines that run from one side of the circle through the origin. One axis begins at 0 degrees, goes through the origin, and ends at 180 degrees. The next starts at 45 degrees and ends at 225 degrees. Another one starts at 90 degrees and ends at 270 degrees. The last starts at 135 degrees and ends at 315 degrees. Each of the four gray concentric circles has a label on their border between the 0 degree and 45 degree marks indicating the length of their radius. From smallest to largest, the circles are labeled 0.5, 1, 1.5, and 2.0. There is a blue line that starts at the origin (the intersection of the four axes) and spirals outward. Below this plot is the caption: 'Figure 1: A line plot on a polar axis.'

You can render documents using the quarto command line tool:

quarto render matplotlib-demo.qmd

Embedded code blocks (in this case some Python code that generates a plot) are run by Quarto, and their output is included in the final document generated by Pandoc.

Note that we use the file extension .qmd to indicate that this isn’t a plain markdown file but rather one with embedded computations to be run by Quarto.

Don’t worry if all the mechanics of this example aren’t obvious, the main takeaway is that Quarto enables you to enhance Pandoc markdown documents with features useful for scientific and technical communication including executable code, cross-references, and much more. The rest of this article provides additional details on how Quarto works.

Markdown Inputs

There are three types of markdown input files that Quarto can render:

  1. Plain markdown (with no embedded code)

  2. Markdown with embedded code chunks

  3. Jupyter notebooks which have a combination of markdown and code cells

R users will typically use the second approach (in fact, existing .Rmd files can be rendered directly with Quarto).

Jupyter users will use either the second or third approach, depending on whether they prefer to work in a text editor or in the standard notebook user interface.

Rendering Output

Use the quarto render command to transform a markdown input file into HTML, a PDF, or any of the other supported output formats. Here are examples of rendering the input types described above:

quarto render document.qmd
quarto render document.ipynb

For plain markdown, the document is sent straight to Pandoc. For markdown with executable code, it is first processed by Jupyter or Knitr, then passed on to Pandoc.

By default, Quarto renders to HTML, however any of Pandoc’s over 40 output formats are supported. For example:

quarto render document.qmd --to pdf
quarto render document.ipynb --to docx

Pandoc supports a wide variety of command line options and all of these options are supported by quarto render. For example:

quarto render document.ipynb --to pdf --toc --number-sections

We’ll talk in more depth about the mechanics of using code chunks in the articles on Running Code. However, for the remainder of this article we’ll just focus on things applicable to all markdown input types whether they contain code or not.

YAML Options

Note that while it is possible to pass many options via the command line, it’s often much more convenient to provide these options within the document itself as YAML front matter. For example:

---
title: "My Document"
author: "Jane Doe"
format: pdf
toc: true
number-sections: true
---

If you do this then the following command is equivalent to the previous example (but no options are provided on the command line b/c they are already defined in YAML):

quarto render document.qmd

Note that in this case rendering with no explicit --to argument results in a PDF, since format: pdf is specified in YAML.

Options may include any of the defined Pandoc metadata variables or defaults. For example, here we take advantage of quite a few more options for PDF generation:

---
title: "My Document"
author: "Jane Doe"
format: pdf
toc: true
number-sections: true
documentclass: report
geometry:
  - top=30mm
  - left=20mm
  - heightrounded
links-as-notes: true
highlight-style: pygments
---

Multiple Formats

The above example includes a simple format: pdf value to set the default format. It’s also possible to provide multiple formats along with YAML options set on a per-format basis. For example, this document defines HTML, PDF, and Word output:

---
title: "My Document"
author: "Jane Doe"
toc: true
toc-depth: 2
format:
  html:
    max-width: 800px
    fontsize: 18px
    html-math-method: katex
  pdf:
    documentclass: report
    margin-left: 30mm
    margin-right: 30mm
  docx:
    number-sections: true
    reference-docx: mytemplate.docx
---

Note that the toc and toc-depth options are shared across all formats, and the options listed below html, pdf, and docx are only applied to their respective formats.

If you render this document without a --to argument, all of the specified formats will be rendered. To render as another format just provide an explicit --to argument:

quarto render document.qmd # render all formats
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

You can learn about the available options for each format in the Pandoc documentation on metadata variables and defaults.

Note that you can share format options across a set of documents using Quarto Projects.

Learn More

Running Code covers creating computational documents with Quarto in more depth, including how to use Quarto with JupyterLab and RStudio.

The Authoring section describes the capabilities of Pandoc markdown, as well as Quarto extensions for Cross References, Figures and Layout, and Callout Blocks.

The output formats section provides additional details on creating HTML, PDF, and MS Word documents, as well as describes a few special output types including Presentations, and pages in Hugo static sites.

Creating a Website and Creating a Book describe some special Quarto project types.