Hello Quarto

Session 1: Getting to know Quarto

Cynthia Huang

Tuesday, July 18, 2023

Pre-workshop instructions

While you wait for the workshop to begin…

• Download or update the latest versions of R, RStudio, Quarto and git:

  • R 4.3 (or 4.2 or above): https://cran.r-project.org
  • RStudio 2023.06.0+421 or above: https://posit.co/download/rstudio-desktop
  • Quarto 1.3.433 or above: https://quarto.org/docs/get-started
  • Git 2.37.1 or above: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

• Install the following packages:

pkg_list <- c(
  "tinytex", "quarto", "knitr", "here", "yaml"
)
install.packages(pkg_list)

• Download and unzip day01-exercises.zip. Then, go to RStudio > File > New Project > Existing Directory and navigate to the unzipped day01-exercises folder and create an RStudio project in there and open it.

Welcome

About Me

• Currently: PhD candidate in EBS
• Previously: Economics at Unimelb, SoDa Labs
• Passionate about research communication and transparency

About You

Write on a sticky-note:

• name of the person next to you
• 1-3 keywords describing their research

02:00

About the Tools

These are the tools we will use without diving too much into how they work. I’m happy to answer questions

• Quarto for collating scientific and technical research inputs into polished
• R and RStudio for editing and rendering Quarto documents and websites
• git and GitHub for publishing your Quarto website

We will not cover any of these tools in depth, but I have included links for more details.

Workshop Goals

This workshop will be a little bit different to your standard Intro to Quarto workshop. We will not cover computation in Quarto

We will focus on:

• features of Quarto that can help you document research code and data:
  • incorporate existing text files (scripts, table outputs etc.)
  • reference management – e.g. in-line citations, cross-references, figure and table numbers
  • generate summary tables and overviews from listing files
• how to publish and share Quarto projects online

Workshop Sessions: Day 1

Session	Objectives
Getting to Know Quarto	What is Quarto? basic Quarto markdown and yaml syntax produce standalone HTML and PDF documents from the same .qmd file produce a single document from multiple existing files
AEA Replication Packages	What goes in a replication package? more Quarto document features and syntax produce a Quarto website from a collection of template files

Workshop Sessions: Day 2

Session	Objectives
Producing and Publishing Websites	What are Quarto websites? Quarto website features and syntax publish the website using git and GitHub Pages
More Quarto for Academics	What else can you do with Quarto? Can I know more about …?

Workshop Expectations

I’ll assume you

• work with small-medium data

• regularly write and debug code

• know some basic LaTex and have heard of markdown

• can use and edit a template even if you don’t fully understand what it is doing

I’ll teach you

• Quarto syntax and formats

• requirements for an AEA replication package

• just enough git and GitHub to publish a website

Workshop format

In class:

• My turn: Lecture segments + live coding
• Our turn: Live coding + follow along
• Your turn: Exercises

Getting Help

• Raise your hand at any time during My Turn and Our Turn segments
• Use sticky notes during Your turn
  • Pink: I’d like some help / I’m stuck / I’m lost
  • Blue: I’m done

Slides, exercises and useful links are all available at:

🔗 cynthiahqy.github.io/monash-quarto-aea

show how to see full-screen and toc

Before we dive in…

Have you completed the prework tasks?

• Download or update the latest versions of R, RStudio, Quarto and git:

  • R 4.3 (or 4.2 or above): https://cran.r-project.org
  • RStudio 2023.06.0+421 or above: https://posit.co/download/rstudio-desktop
  • Quarto 1.3.433 or above: https://quarto.org/docs/get-started
  • Git 2.37.1 or above: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

• Install the following packages:

pkg_list <- c(
  "tinytex", "quarto", "knitr", "here", "yaml"
)
install.packages(pkg_list)

• Download and unzip day01-exercises.zip. Then, go to RStudio > File > New Project > Existing Directory and navigate to the unzipped day01-exercises folder and create an RStudio project in there and open it.

What is Quarto?

Quarto …

• is a new, open-source, scientific, and technical publishing system built on Pandoc

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

Quarto …

• is a new, open-source, scientific, and technical publishing system built on Pandoc

• includes a visual markdown editor for WYSISYG editing
• is a command line interface (CLI) that the renders plain text formats (.qmd, .rmd, .md) into static PDF/Word/HTML reports, books, websites, presentations and more.

Aside: Alternative Workspaces

My Turn: A Tour of Quarto in RStudio

Show off features: - new project from day01-exercises - new file in Rstudio - remove CODE chunks & focus on Markdown Features - use Help > Markdown Quick Reference - visual mode <–> source mode - formats - HTML, PDF - render options - preview in pane, or window - render on save - show terminal: quarto command line interface - quarto render my_first_doc.qmd - quarto preview my_first_doc.qmd

Your Turn: my_first_doc.qmd

we won’t go in-depth with markdown features, but explore and ask questions!

• Create or Open the Rstudio Project day01-exercises
• Go to File > New File > Quarto Document to create a new document in Visual mode.
• Replace the Code section with your own content.
• Render the document then switch to Source mode. Save the file as my_first_doc.qmd
• Use Help > Markdown Quick Reference to add more content.
• Re-render and compare changes with your neighbours.
• Take note of any features you would like to know more about.

15:00

Rendering Options in Rstudio

1. Option 1: In RStudio as a background job, and preview the output.

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

3. 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: Rendering in Rstudio

• Open the last .qmd file you were working on in RStudio.
• Compare behavior of rendering with
  • RStudio > Render,
  • using the CLI in the Terminal: quarto render my_first_doc.qmd,
  • using quarto::quarto_render("my_first_doc.qmd")
• Try different Render options in Rstudio:
  • Rstudio > Render on Save Tickbox
  • Rstudio > Cog Icon > Preview in Pane

05:00

Under the Hood

• Rstudio or the quarto package calls the Quarto command line interface (CLI) – quarto render my_doc.qmd
• any R/Python/Julia code or features are evaluated by knitr or jupyter which return 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

• Here is an example of a Lua filter that converts strong emphasis to small caps, from https://pandoc.org/lua-filters.html:

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 will use a Quarto extension Lua filter called include-code-files later in this workshop, but won’t go into details of how they work or how to write them.