Welcome to Quarto

A scientific and technical publishing system built on Pandoc

Introduction

Quarto is an open-source scientific and technical publishing system built on Pandoc. Quarto documents are authored using markdown, an easy to write plain text format.

In addition to the core capabilities of Pandoc, Quarto includes:

  1. Support for embedding output from Python, R, and Julia via integration with Jupyter and Knitr .

  2. A variety of extensions to Pandoc markdown useful for technical writing including callouts (admonitions), cross-references, sub-figures, layout panels, hover-able citations and footnotes, and more.

  3. A project system for rendering groups of documents at once, sharing options across documents, and producing aggregate output like books and websites.

  4. HTML output based on Bootstrap (including support for Bootswatch themes).

  5. Automatic installation of required LaTeX packages when rendering PDF output.

The overall design of Quarto is influenced heavily by R Markdown, however unlike R Markdown the architecture is language agnostic. In it’s current iteration, Quarto can render plain markdown, Jupyter Notebooks, and Knitr (Rmd) documents.

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:

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.

Note

While this example demonstrates rendering a .qmd markdown file, Quarto is also compatible with other computational markdown formats like Jupyter Notebooks (.ipynb) and R Markdown (.Rmd).

Getting Started

Installation will get you up and running with Quarto (including additional dependencies required for computational documents).

Quarto Basics will help you learn the core mechanics of rendering markdown from the command line as well as how to specify document formats and options.

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