Hello Quarto

Hello Quarto: A World of Possibilities
(for Reproducible Publishing)

Dr. Mine Çetinkaya-Rundel

Duke University + Posit

2023-06-06

Pre-workshop instructions

While you wait for the workshop to begin…

Decide which option you prefer and follow the steps.

Option 1: Own setup

pkg_list <- c("tidyverse", "gt", "ggthemes", "palmerpenguins", "quarto", "here")
install.packages(pkg_list)

Option 2: Posit Cloud

Click here to join the Posit Cloud space for the workshop. Log in using Google, GitHub, or Posit (e.g., shinyapps.io or Posit Cloud) authentication, join the space, and then click on Content on the top navigation bar.

Welcome

About me

  • Mine Çetinkaya-Rundel

  • Professor of the Practice, Duke University - Statistical Science

  • Developer Educator, Posit

  • R Markdown users/educators for 10+ years, Quarto users/educators for 1+ years

About you

Meet 1-2 people around you!

01:00

Workshop structure

  • My turn: Lecture segments + live coding

  • Our turn: Live coding + follow along

  • Your turn: Exercises

Getting help / questions

  • Don’t hesitate to raise your hand to ask a question throughout the workshop

  • I might be able to answer / help on the spot, or wait till the next “your turn” break to do so

Hello Quarto

Meeting you where you are

I’ll assume you

  • know some R

  • have worked in RStudio

  • want to learn about Quarto

I’ll teach you

  • Quarto syntax and formats

  • More Markdown

  • Even more R along the way!

Checking in one more time

Have you completed the following?

Decide which option you prefer and follow the steps.

Option 1: Own setup

pkg_list <- c("tidyverse", "gt", "ggthemes", "palmerpenguins", "quarto", "here")
install.packages(pkg_list)

Option 2: Posit Cloud

Click here to join the Posit Cloud space for the workshop. Log in using Google, GitHub, or Posit (e.g., shinyapps.io or Posit Cloud) authentication, join the space, and then click on Content on the top navigation bar.

Let’s get started!

What is Quarto?

Quarto …

  • is a new, open-source, scientific, and technical publishing system
  • aims to make the process of creating and collaborating dramatically better
A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

Quarto

With Quarto you can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more.


just like R Markdown…


but not just like it, there’s more to it…

Quarto …

unifies + extends the R Markdown ecosystem

Quarto …

unifies + extends the R Markdown ecosystem


unifies for people who love R Markdown

Quarto …

unifies + extends the R Markdown ecosystem


unifies for people who love R Markdown

extends for people who don’t know R Markdown

Quarto unifies + extends R Markdown

  • Consistent implementation of attractive and handy features across outputs: tabsets, code-folding, syntax highlighting, etc.
  • More accessible defaults as well as better support for accessibility
  • Guardrails, particularly helpful for new learners: YAML completion, informative syntax errors, etc.
  • Support for other languages like Python, Julia, Observable, and more via Jupyter engine for executable code chunks.

A tour of Quarto



Sit back and enjoy!

Your turn

Open hello-penguins.qmd in RStudio and with the visual editor. Render the document. Update your name and re-render. Inspect components of the document and make one more update and re-render. Compare notes with neighbors about updates you’ve made and note any aspects of the document that are not clear after the tour and your first interaction with it.

05:00

Quarto CLI

Revisit: What is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static PDF/Word/HTML reports, books, websites, presentations and more.

mine$ quarto --help

  Usage:   quarto 
  Version: 1.3.353

  Description:

    Quarto CLI

  Options:

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

  Commands:

    render          [input] [args...]     - Render files or projects to various document types.        
    preview         [file] [args...]      - Render and preview a document or website project.          
    serve           [input]               - Serve a Shiny interactive document.                        
    create          [type] [commands...]  - Create a Quarto project or extension                       
    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.                
    add             <extension>           - Add an extension to this folder or project                 
    install         [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.         
    help            [command]             - Show this help or the help of a sub-command.

Quarto, more than just knitr

We learned from 10 years of literate programming with knitr + rmarkdown

Quarto, more than just knitr

Quarto: More than just knitr

Under the hood

  • knitr or jupyter evaluates R/Python/Julia code and returns a .md file along with the evaluated code
  • Quarto applies Lua filters + CSS/LaTeX which is then evaluated alongside the .md file by Pandoc and converted to a final output format

Aside: Lua filters

return {
  {
    Strong = function (elem)
      return pandoc.SmallCaps(elem.c)
    end,
  }
}
  • Lua filters written by R/Python/Julia developers should be interchangeable between formats - not language specific!
  • We won’t go into the details of writing Lua filters in this workshop, and you don’t need to worry about learning about Lua filters unless you’re working on extending Quarto.

From the comfort of your own homeworkspace

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

Quarto workflow

Rendering a Quarto file in RStudio via the Render button calls quarto render in a background job, preventing Quarto rendering from cluttering up the R console, and gives you and easy way to stop:

Rendering

  1. Option 1: In RStudio as a background job, and preview the output.
  1. Option 2: In the Terminal via quarto render:
quarto render document.qmd # defaults to html
quarto render document.qmd --to pdf
quarto render document.qmd --to docx
  1. Option 3: In the R console, via the quarto R package:
library(quarto)

quarto_render("document.qmd") # defaults to html
quarto_render("document.qmd", output_format = "pdf")

Quarto formats

One install, “Batteries included”

  • RMarkdown grew into a large ecosystem, with varying syntax.

  • Quarto comes “batteries included” straight out of the box

    • HTML reports and websites
    • PDF reports
    • MS Office (Word, Powerpoint)
    • Presentations (Powerpoint, Beamer, revealjs)
    • Books
  • Any language, exact same approach and syntax

Many Quarto formats

Feature R Markdown Quarto
Basic Formats

html_document

pdf_document

word_document

html

pdf

docx
Beamer beamer_presentation beamer
PowerPoint powerpoint_presentation pptx
HTML Slides

xaringan

ioslides

revealjs

 revealjs
Advanced Layout

tufte

distill

 Quarto Article Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References

html_document2

pdf_document2

word_document2

 Quarto Crossrefs
Websites & Blogs

blogdown

distill

Quarto Websites

Quarto Blogs
Books bookdown Quarto Books
Interactivity Shiny Documents Quarto Interactive Documents
Journal Articles rticles Journal Articles
Dashboards flexdashboard Coming soon!

Your turn

In RStudio, go to File > New File > Quarto document to create a Quarto document with HTML output. Render the document, which will ask you to give it a name – you can use my-first-document.qmd.

Use the visual editor for the next steps.

  • Add a title and your name as the author.

  • Create two sections, one with fact you want to learn and your favorite thing about R.

  • Add a table of contents.

  • Stretch goal: Change the html theme to sketchy.

05:00

Wrap up

What about R Markdown?

  • You can render existing R Markdown documents with Quarto and you can rename them to .qmd files to turn them into Quarto documents.

  • You don’t have to do this – R Markdown continues to be maintained.

  • However, new features are being developed for Quarto.

  • Additionally, Quarto

    • Offers “batteries included” shared syntax across formats

    • Allows you to choose your own editor and your preferred data science language

    • Comes with richer and more accessible features out of the box

    • Is actively developed

Questions

Any questions / anything you’d like to review before we wrap up this module?

One last thing!

Where does the name “Quarto” come from?

🔗 mine.quarto.pub/quarto-monash