Quarto for the curious


Tom Mock, RStudio PBC

 rstd.io/quarto-curious

2022-07-27

You are sneaky!

We don’t talk about Quarto

A tweet by Alison Hill revealing her blogpost on Quarto. Over the weekend, I wrote up my notes about using and teaching Quarto, based on my experiences working with the development team for over a year. I think (hope?) it is safe to talk about it now

Quarto excitement!

A tweet by Kelly Bodwin revealing her excitement about Quarto. Did I stay up until 6am before the first night of class converting all my R Markdown materials to @quarto_dev? Yes, yes I did. Do I regret it? No, I do not. It's pretty rad my dudes.

Quarto excitement, in Python!

A tweet by Jeremy Howard, FYI nbdev will be moving to Quarto and Fastdoc probably too

A tweet by Hamel Husain, 'I'm going to be announcing an epic new version of nbdev in tihs talk! The next version of nbdev is going to be built on top of Quarto'

Others had more Quarto questions…

Tweet by Andrew Heiss, I'm seeing more and more .qmd files - I'm tempted to switch to Quarto, is it safe enough to do that now?

A tweet by Danielle Navarro, I admit I'm curious and want to learn. How much of RMarkdown ecosystem ports over naturall? Can I make xaringan-like slides or is that not feasible right now?

So what is Quarto?



Quarto is the next-generation of RMarkdown.

For everyone.

So what is Quarto?

Quarto® is an open-source scientific and technical publishing system built on Pandoc.

  • quarto is a language agnostic command line interface (CLI)
thomasmock$ quarto --help
  Usage:   quarto
  Version: 1.0.36

  Options:
    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    create-project  [dir]               - Create a project for rendering multiple documents          
    convert         <input>             - Convert documents to alternate representations.            
    pandoc          [args...]           - Run the version of Pandoc embedded within Quarto.          
    run             [script] [args...]  - Run a TypeScript, R, Python, or Lua script.                
    install         <type> [target]     - Installs an extension or global dependency.                
    publish         [provider] [path]   - Publish a document or project. Available providers include:
    check           [target]            - Verify correct functioning of Quarto installation.

RMarkdown for literate programming

Quarto for literate programming

diagram of converting a Qmd document via knitr/pandoc into markdown and then into output formats

Quarto for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

So what is a .qmd?

A Quarto document i.e. a .qmd is a plain text file

  • Metadata (YAML)
format: html
engine: knitr
format: html
engine: jupyter
  • Code
```{r}
library(dplyr)

mtcars |> 
  dplyr::group_by(cyl) |> 
  dplyr::summarize(mean = mean(mpg))
```
```{python}
from siuba import _, group_by, summarize
from siuba.data import mtcars
(mtcars
  >> group_by(_.cyl)
  >> summarize(avg_mpg = _.mpg.mean())
  )
```
  • Text
# Heading 1
This is a sentence with some **bold text**, some *italic text* and an 
![image](image.png){fig-alt="Alt text for this image"}.

Patrick

One install, batteries included

One install, “Batteries included”

  • Quarto’s 1.0 release comes pre-installed with RStudio v2022.07.1 and beyond! Any language, same syntax and approach
Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References
Websites & Blogs
Books
Interactivity Shiny Documents Quarto Interactive Documents
Paged HTML pagedown Summer 2022
Journal Articles rticles Summer 2022
Dashboards flexdashboard Fall 2022

Comfort of your own workspace

roam in color

Comfort of your own workspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

Auto-completion in RStudio + VSCode


Both RStudio and VSCode with the Quarto extension have rich auto-completion

Chunk option

A gif of auto-completion of a R chunk inside RStudio

YAML

A gif of auto-completion and search for YAML options inside RStudio

Interactivity with {htmlwidgets} or shiny

library(leaflet)
leaflet() %>%
  addTiles() %>%  # Add default OpenStreetMap map tiles
  addMarkers(lng=-77.0147, lat=38.7818, popup="We are here, together!")

Interactivity with Jupyter Widgets

from ipyleaflet import Map, Marker, basemaps, basemap_to_tiles
m = Map(
  basemap=basemap_to_tiles(
    basemaps.NASAGIBS.ModisTerraTrueColorCR, "2017-04-08"
  ),
  center=(38.7818, -77.0147),
  zoom=4
)
m.add_layer(Marker(location=(38.7818, -77.0147)))
m

Interactivity, Observable

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

Next-Gen RMarkdown, unification

RMarkdown is not going away, but new features built into knitr and Quarto

diagram of converting a Quarto document via knitr/pandoc into markdown and then into output formats

What to do with my existing .Rmd?

For some of you - nothing changes! Keep using RMarkdown if you’d like.

However, most existing .rmd can be rendered as-is via Quarto or with some light editing.

quarto render my-favorite.rmd --to html

Next-Gen RMarkdown, unified document layout

quarto render boston-terrier.qmd --to html
quarto render boston-terrier.qmd --to pdf

A screenshot of a HTML article about Boston Terriers, the document has an image in the right hard margin, a floating table of contents, and different sections split up by headers

HTML

A screenshot of a PDF article about Boston Terriers, the document has an image in the right hard margin, a floating table of contents, and different sections split up by headers

PDF

Next-Gen RMarkdown, extended for other languages

The main technical difference between Quarto and R Markdown is that Quarto makes heavy use of Pandoc’s Lua filters. - Yihui Xie 1

We are meeting Julia/Python users in their native language

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

What to do with my existing .ipynb?

You can keep using them!


quarto render my-favorite.ipynb --to html --execute


Quarto can help convert back and forth between plain text .qmd and .ipynb:

quarto convert --help

Usage:   quarto convert <input>

Description:

    Convert documents to alternate representations.

Convert notebook to markdown:                quarto convert doc.ipynb                
Convert markdown to notebook:                quarto convert doc.qmd                  
Convert notebook to markdown, write to file: quarto convert doc.ipynb --output doc.qmd

Collaboration between multi-lingual teams

A tweet by Gordon Shotwell, It's very hard to get Python users to use rmarkdown because you need R to render the document. Having a generic toolkit better for usability and branding.

Edit: Replaced mispelling of “tookis” with “toolkit”

Extending Quarto with extensions

Shortcodes

  • Replace inline “short codes” with output.
{{< fa thumbs-up >}}


Filters

  • Affect rendering of specific items

A screenshot of a code chunk

Formats

  • Add entirely custom new formats
---
title: "Cool Company 2022 Presentation"
format: coolco-revealjs
---

Quarto Publish

quarto publish --help

  Usage:   quarto publish [provider] [path]
  Version: 1.0.36                          
                                           
  Description:
    Publish a document or project. Available providers include:
                                                               
     - Quarto Pub (quarto-pub)                                 
     - GitHub Pages (gh-pages)                                 
     - RStudio Connect (connect)                               
     - Netlify (netlify)

Screenshot of the quartopub.com website

What about for Data Science at Work?

  • Use Quarto in RStudio Workbench (v2022.07.1) and RStudio Connect (v2022.07.0)!

diagram of Rendering a complex data science workflow via RStudio Connect - Quarto is used as the rendering mechanism for the notebooks and code

https://solutions.rstudio.com/example/bike_predict/

Quarto, crafted with love and care

Development of Quarto is sponsored by RStudio, PBC. The same core team works on both Quarto and R Markdown:

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Quarto

  • Batteries included, shared syntax across output types and languages
  • Choose your own editor and your preferred data science language
  • RMarkdown still maintained, but majority of new features built into Quarto

Follow @quarto_pub or me @thomas_mock on Twitter to stay up to date!

rstudio::conf 2022

Web resources

Why the name “Quarto”?1

rstd.io/quarto-curious by @thomas_mock