Intro to Quarto

An open source publishing system for
scientific and technical communication
https://quarto.org
 

J.J. Allaire — Nov. 28, 2022

What is Quarto?

Quarto is an open-source scientific and technical publishing system that builds on standard markdown with features essential for scientific communication.

  • Computations: Python, R, Julia, Observable JS
  • Markdown: Pandoc w/ many enhancements
  • Output: Documents, presentations, websites, books, blogs

Literate programming system in the tradition of Org-mode, Sweave, Jupyter Book, Weave.jl, R Markdown, iPyPublish, etc.

Origins

  • Open source project sponsored by Posit, PBC (formerly RStudio, PBC)
  • 10 years of experience with R Markdown (a similar system that was R-specific) convinced us that the core ideas were sound.
  • The number of languages and runtimes used for scientific discourse is very broad (and expanding!)
  • Quarto is a ground-up re-imagining of R Markdown that is fundamentally multi-language and multi-engine.

Goals

  • Computational Documents (Reproducibility)

  • Scientific Markdown (Complex technical documents)

  • Single Source Publishing (Web, PDF, Office, etc.)

Goal: Computational Documents

  • Documents that incorporate the source code required for their production
  • Notebook and plain text flavors
  • Automation and reproducibility

Computational Engines

Quarto has a pluggable computation system that allows for compatibility with today’s standards along with the ability to evolve to work with new standards:

Jupyter Engine

Notebook workflow (no execution occurs by default):

Plain text workflow (.qmd => .ipynb then execute cells):

Jupyter: Notebook Workflow

Author within e.g. Jupyter Lab (side by side preview for HTML or PDF output):

Jupyter: Plain Text Workflow

Markdown document with cross references and executable code blocks:

---
title: "matplotlib demo"
jupyter: python3
---

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 * np.arange(0, 2, 0.01)
fig, ax = plt.subplots(subplot_kw = {'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
```

Render to various output formats:

quarto render hello.qmd --to html
quarto render hello.qmd --to pdf
quarto render hello.qmd --to docx

Goal: Scientific Markdown

Markdown Extensions

  • Citations
  • Cross references
  • LaTeX math
  • Diagrams
  • Figure panels
  • Callouts
  • Advanced page layout

Or add your own: https://quarto.org/docs/extensions/

Goal: Single Source Publishing

https://coko.foundation/articles/single-source-publishing.html

Publishing Formats

  • Documents (HTML, PDF, Word, ODT, Ipynb, etc.)

  • Presentations (HTML, PDF, PowerPoint, etc.)

  • Websites & Blogs (Quarto, Hugo, Docusaurus, etc.)

  • Books (HTML, PDF, Word, ePub, Asciidoc, etc.)

  • Journal Articles (LaTeX, HTML, Ipynb, JATS, etc.)

Some Examples

https://quarto.org/docs/gallery

Python for Data Analysis, 3E

Practical Deep Learning (fast.ai)

Notebooks and Quarto

Ways to use Jupyter Notebooks with Quarto:

  • Authoring—Using notebooks as an end-to-end authoring tool for a manuscript or report.

  • Computations—Using notebooks as source of reproducible computations for a document.

  • Publishing—Providing interactive supplements to articles published in print or on the web.

Notebook Authoring

Author the entire manuscript within a notebook editor like Jupyter Lab (side by side preview for HTML or PDF output):

Notebook Computations

  • Notebook as a computational medium only (as opposed to a medium for both prose and computation)

  • Staged workflow where computations are embedded within documents for publication (retaining ability to re-execute computations for reproducibility)

Notebook Computations (cont.)

Markdown document embeds figure from notebook:

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

::: {#fig-polar}

{{< embed notebook.ipynb#fig-polar >}}

A line plot on a polar axis.
:::

Notebook Publishing

Create notebook output alongside traditional formats (LaTeX, HTML, etc.). For example, here is metadata for an American Chemical Society article that produces multiple outputs:

format:
  acs-pdf:
    keep-tex: true
    journal:
      id: jacsat 
      layout: traditional 
      abbreviations: IR,NMR,UV
  acs-html: 
    fig-width: 6
    fig-height: 4
  ipynb: 
    fig-width: 7
    fig-height: 5

Integration: Jupyter Book and Nbdev

  • Quarto and Jupyter Book use distinct base markdown systems (Pandoc and MyST) so source level integration is challenging.

    However, both projects use Jupyter Notebooks as a content source, and we are working together (via Notebooks Now) on common publishing formats for manuscripts that are created from notebooks.

  • Nbdev from fast.ai now includes integrated support for generating Quarto websites from library documentation written in notebooks.