Hello Quarto

Intro Quarto @ Cascadia R Conf

Charlotte Wickham

Posit, PBC

While you wait for the workshop to begin, be sure you’ve got all the tools needed for the workshop:

 

https://charlotte.quarto.pub/cascadia


In addition, please download and open the exercises for this workshop:

usethis::use_course("https://bit.ly/cscd-exercises")

Code of Conduct

Cascadia R Conference is dedicated to providing a harassment-free conference experience for everyone regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion. We do not tolerate harassment of conference participants in any form. Sexual language and imagery is not appropriate for any conference venue, including talks. Conference participants violating these rules may be sanctioned or expelled from the conference without a refund at the discretion of the conference organizers.

Harassment includes verbal comments that reinforce social structures of domination related to gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age, religion; sexual images in public spaces; deliberate intimidation; stalking; following; harassing photography or recording; sustained disruption of talks or other events; inappropriate physical contact; and unwelcome sexual attention. Participants asked to stop any harassing behavior are expected to comply immediately.

If a participant engages in harassing behavior, the conference organizers may take any action they deem appropriate, including warning the offender or expulsion from the conference with no refund. If you are being harassed, notice that someone else is being harassed, or have any other concerns, please contact a member of conference staff immediately or email . Conference staff will be happy to assist those experiencing harassment to feel safe for the duration of the conference. We value your attendance.

We expect attendees, sponsors, volunteers, and speakers to adhere to the code of conduct during the conference and in related online communities and social media. We will be monitoring all social media related to the conference throughout the year. If you have any questions, email

About me

Charlotte Wickham

  • Developer Educator, Posit
  • R Markdown user for 11+ years
  • Quarto user for 2+ years

Our Teaching Assistants

Jadey Ryan

Lydia Gibson

About you

Please share:

  • Name
  • What do you use R for?
05:00

Meeting you where you are

These materials are pitched at someone who:

  • knows some R

  • has worked in RStudio

  • wants to learn about Quarto

I’ll teach you

  • Quarto Workflow

  • Components of a Quarto Document

  • Specific features: markdown, tables, figures, callouts, code blocks

Workshop structure

  • My turn:

    • Lecture segments + live coding
    • Feel free to just watch, take notes, browse docs, or tinker around in RStudio

  • Our Turn:

    • Live coding + follow along
    • If problems crop up for you, ask away, but I might ask you to hold on

  • Your Turn: Practice exercises for you. Use your post-it notes.

Checking in one more time

1. Software

Download and install the latest versions of R, RStudio, and Quarto:

2. R Packages

Install the following packages:

pkg_list <- c("tidyverse", "gt", "ggthemes", "palmerpenguins", 
              "quarto", "usethis")

install.packages(pkg_list)

3. Exercises

Download and open the exercises for this session. The easiest way is to run this line of R code at the console in RStudio.

usethis::use_course("https://bit.ly/cscd-exercises")

If that doesn’t work, you can download a zip file of the exercises here, then open the directory. The qmd files can be opened in RStudio.

Let’s get started!

What is Quarto?

Quarto …

  • is a new, open-source, scientific, and technical publishing system.
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 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
  • 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 . . .

  1. Render the document.
  2. Update your name and re-render.
  3. Inspect components of the document and make one more update and re-render.
  4. 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.
10:00

How it Works

Introducing the 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.

Terminal
$ quarto --help

Usage:   quarto
Version: 1.5.23

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               
  use        <type> [target]       - Automate document or project setup tasks.          
  add        <extension>           - Add an extension to this folder or project         
  update     [target...]           - Updates an extension or global dependency.         
  remove     [target...]           - Removes an extension.                              
  convert    <input>               - Convert documents to alternate representations.    
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.  
  typst      [args...]             - Run the version of Typst embedded within Quarto.   
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.        
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).
  uninstall  [tool]                - Removes an extension.                              
  tools                            - Display the status of Quarto installed dependencies
  publish    [provider] [path]     - Publish a document or project to a provider.       
  check      [target]              - Verify correct functioning of Quarto installation. 
  help       [command]             - Show this help or the help of a sub-command.

Under the hood

  • knitr, jupyter, or julia engine 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

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

Rendering

  1. Option 1: In RStudio with 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")

Your turn

  • Open the last .qmd file you were working on in RStudio.
  • Compare behavior of rendering with
    • RStudio > Render,
    • using the CLI with quarto render, and
    • in the R console via quarto_render().
  • If you’re an RStudio user, brainstorm why you might still want to know about the other two ways of rendering Quarto documents.
03:00

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 Quarto R Markdown
Basic Formats

html

pdf

docx

html_document

pdf_document

word_document
Beamer beamer beamer_presentation
PowerPoint pptx powerpoint_presentation
HTML Slides revealjs

xaringan

ioslides

revealjs
Advanced Layout Quarto Article Layout

tufte

distill

Many Quarto formats

Feature Quarto R Markdown
Cross References Quarto Crossrefs

html_document2

pdf_document2

word_document2
Websites & Blogs

Quarto Websites

Quarto Blogs

blogdown

distill
Books Quarto Books bookdown
Interactivity Quarto Interactive Documents Shiny Documents
Journal Articles Journal Articles rticles
Dashboards Quarto Dashboards flexdashboard

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

    • Offers “batteries included” shared syntax across formats

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

    • Comes with richer features out of the box

    • Is actively developed

Questions

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

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 things you would like to use Quarto for and a second with your favorite thing about R.

  • Add a table of contents.

  • Stretch goal: Change the html theme to sketchy.

10:00

charlotte.quarto.pub/cascadia