Introduction to Quarto

J.J. Allaire

July 11th, 2022

What is Quarto?

Quarto is the next generation of R Markdown

Quarto Overview

https://quarto.org

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, Weave.jl, R Markdown, iPyPublish, Jupyter Book, etc.

Origins

  • Open source project sponsored by 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.
  • Quarto is a ground-up re-imagining of R Markdown that is fundamentally multi-language and multi-engine.

Goal: Computational Documents

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

Goal: Scientific Markdown

Goal: Single Source Publishing

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

Why a New System?

  • The number of languages and runtimes used for scientific discourse is very broad (and the Jupyter ecosystem in particular is extraordinarily popular).
  • Quarto is at its core multi-language and multi-engine (supporting Knitr, Jupyter, and Observable today and potentially other engines tomorrow).
  • On the other hand, R Markdown is heavily tied to R which limits the number of peoople it can benefit.
  • Quarto is RStudio's attempt to bring R Markdown to everyone!

Quarto Engines

  • Knitr
  • Jupyter
  • Observable JS
  • Others possible…

Knitr Engine

For R, Quarto still uses Knitr under the hood.

This means that for the most part the vast majority existing Rmd files can be rendered unmodified w/ Quarto.

Note that the standard syntax for chunk options has changed (old syntax nevertheless still works):

```{r}
#| echo: false
#| label: fig-cars
#| fig-cap: "Cars"

plot(cars)
```

Knitr Engine

Jupyter Engine

The Jupyter engine supports the use of Python, Julia, and any other language that has a Jupyter kernel.

Jupyter supports two input file formats:

  • Traditional notebooks (.ipynb)
  • Markdown w/ chunks (.qmd)

Hello Jupyter: https://quarto.org/#hello-quarto

Jupyter Engine: Tooling

Side-by-side preview for JupyterLab, VS Code, Emacs, etc.:

$ quarto preview notebook.ipynb

Observable JS

Quarto includes native support for Observable JS, a set of enhancements to vanilla JavaScript created by Mike Bostock (also the author of D3).

Observable JS is distinguished by its reactive runtime, which is especially well suited for interactive data exploration and analysis.

Demo: https://quarto.org/docs/interactive/ojs/#example

Shared Core Syntax

Core features have similar expression across formats:

  • Code folding

  • Tabsets

  • Theming

  • Anchor links

R Markdown

The R Markdown ecosystem was built over nearly a decade (resulting in lots of inconsistency & duplication)

Packages
  • tufte
  • rticles
  • revealjs
  • xaringan
  • bookdown
  • blogdown
  • distill
Features
  • Floating TOC
  • Code folding / copying
  • Syntax highlighting
  • Page layout
  • Theming
  • Tabsets
  • Section anchors

Code folding / copying

Code 
```{r}
#| code-fold: true

library(ggplot2)
dat <- data.frame(cond = rep(c("A", "B"), each=10),
                  xvar = 1:20 + rnorm(20,sd=3),
                  yvar = 1:20 + rnorm(20,sd=3))

ggplot(dat, aes(x=xvar, y=yvar)) +
    geom_point(shape=1) + 
    geom_smooth() 
```

Tabsets

fizz_buzz <- function(fbnums = 1:50) {
  output <- dplyr::case_when(
    fbnums %% 15 == 0 ~ "FizzBuzz",
    fbnums %% 3 == 0 ~ "Fizz",
    fbnums %% 5 == 0 ~ "Buzz",
    TRUE ~ as.character(fbnums)
  )
  print(output)
}
def fizz_buzz(num):
  if num % 15 == 0:
    print("FizzBuzz")
  elif num % 5 == 0:
    print("Buzz")
  elif num % 3 == 0:
    print("Fizz")
  else:
    print(num)

Tabset syntax: https://quarto.org/docs/output-formats/html-basics.html#tabsets

Theming

Universal themeing system (based on SCSS) for all HTML output formats (shared by HTML and RevealJS slides, extendable to work with anything).

Based on core variables defined by bslib (so fully compatible with Shiny, Flexdashboard, & R Markdown themes).

Sample theme file: https://quarto.org/docs/output-formats/html-themes.html#theme-options

New Features

  • Cross references
  • Advanced page layout
  • Figure/layout panels
  • Callouts
  • YAML intelligence

Cross References

Cross reference figures, tables, equations, sections, theorems, etc.

Plain markdown: https://quarto.org/docs/authoring/cross-references.html#subfigures

Knitr/Jupyter: https://quarto.org/docs/authoring/cross-references.html#computations

Advanced page layout

Advanced page layout features inspired by Tutfe, Distill, and Hugo Prose.

  • Figures and tables that span the entire page
  • Use of margin for figures, equations, captions, asides, footnotes, and citations
  • Responsive show/hide of site navigation and TOC
  • Examples: HTML, PDF

Figure/Layout Panels

::: {layout="[[40,-20,40], [100]]"}
![Surus](surus.png)
![Hanno](hanno.png)
![Lin Wang](lin-wang.png)
:::

Callouts

Work in HTML, PDF, MS Word, and ePub output

YAML Intelligence

  • YAML code completion for config files, front matter, and chunk options
  • Real-time diagnostics and clear errors at render time for invalid YAML

Completion

Diagnostics

Advanced Formats

  • Websites

  • Books

  • Blogs

  • Presentations

Quarto Websites

  • Arbitrary content depth / organization

  • Multi-level navigation (navbar / sidebar / hybrid)

  • Full text search (client side or Algolia)

  • Freezing computational output

  • Example: https://quarto.org

Quarto Books

Quarto Blogs

Quarto Presentations

https://quarto.org/docs/presentations/revealjs/demo/

  • Based on a (heavily customized) version of RevealJS:
    • Image, video, and iframe backgrounds
    • PDF Printing
    • Speaker view
    • Plugin system
  • Many features inspired by xaringanExtra:
    • Chalkboard / drawing on slides
    • Multicast (synced presenter / viewer slides)
    • Slide tone (for accessibility)
    • Absolute positioning of slide elements

Quarto Tools

  • Quarto CLI

  • RStudio IDE

  • VS Code Extension

  • Visual Editor

Quarto CLI

Core component that drives Quarto rendering. This is the only thing you need to render plain markdown (it includes Pandoc 2.18).

  • Add knitr to render documents w/ R
  • Add jupyter to render with Jupyter kernels

Like git, this is a system level compontent that is used by RStudio, VS Code, Jupyter Lab, terminal sessions, etc.

Download/install: https://quarto.org/docs/get-started/

RStudio IDE

Current release of RStudio IDE has Quarto tooling on-par w/ R Markdown tooling

VS Code Extension

https://marketplace.visualstudio.com/items?itemName=quarto.quarto

  • Render command with integrated preview pane
  • Syntax highlighting for markdown and embedded languages
  • Completion for embedded languages (e.g. Python, R, Julia, LaTeX, etc.)
  • Completion and diagnostics for project files and document/cell options
  • Commands and key-bindings for running cells and selected line(s)
  • Live preview for embedded mermaid and graphviz diagrams
  • Assist panel for contextual help, image preview, and math preview
  • Code snippets for common markdown constructs
  • Code folding and document outline for navigation within documents
  • Workspace symbol provider for navigation across project files

Visual Editor

https://quarto.org/docs/visual-editor/

  • The Quarto visual editor provides a WYSIWYM editing interface for all of Pandoc markdown

  • Tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, etc.

  • Includes support for executing code cells and viewing their output inline.

Learning More

Quarto at rstudio::conf(2022)