Quarto for the curious


Tom Mock, RStudio/posit 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?

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.37

Commands:
  render  [input] [args...] - Render input file(s) to various document types.            
  preview [file] [args...]  - Render and preview a document or website project.          
  publish [provider] [path] - Publish a document or project.

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

A .qmd is a plain text file

  • Metadata (YAML)
format: html
engine: knitr
format: html
engine: jupyter
  • Code
```{r}
library(dplyr)
mtcars |> 
  group_by(cyl) |> 
  summarize(mean = mean(mpg))
```
```{python}
from siuba import *
(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"}.

One install, “Batteries included”

  • Quarto’s 1.0 release comes pre-installed with RStudio v2022.07.1 and beyond!

RStudio 2022.07.1+554 'Spotted Wakerobin', July 25th, 2022 New: Update Quarto to 1.0.36

Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout
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

YAML

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

Chunk option

A gif of auto-completion of a R chunk 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, any bugs will be fixed, 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.

quarto render my-favorite.rmd --to html

Quarto, 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

Quarto, 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

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