Hello Quarto

What is Quarto?

Quarto® is an open-source scientific and technical publishing system built on Pandoc that 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

  • Consistent implementation of attractive and handy features across outputs
  • More accessible defaults as well as better support for accessibility
  • Guardrails, particularly helpful for new learners: YAML completion, code option completion
  • Support for other languages like Python, Julia, and more

A compilation of nine hex stickers, each from a package unique to RMarkdown (xaringan, distill, blogdown, bookdown, etc.).


The quarto logo, a blue circle with light blue cross sections.}

Quarto makes moving between formats straightforward

Document

lesson-1.qmd

title: "Lesson 1"
format: html

Presentation

lesson-1.qmd

title: "Lesson 1"
format: revealjs

Website

_quarto.yml

project:
  type: website

website: 
  navbar: 
    left:
      - lesson-1.qmd

Let’s get started!

  • Open RStudio
  • Click on “File”
  • Select “New File”
  • Select “Quarto Document”
    • Fill in the title and author
    • Select HTML for the format option
  • Click “Create”!

A Quarto Document

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "May 22nd, 2021"
format: 
  html:
    code-fold: true
---

## Air Quality

@fig-airquality further explores the impact of temperature 
  on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)
ggplot(airquality, 
       mapping = aes(x = Temp, y = Ozone)
       ) + 

  geom_point() + 
  geom_smooth(method = "loess"
)
```

A preview of how a rendered Quarto document looks.

Anatomy of a Quarto document

YAML

processed in many stages of the rendering process and can influence the final document in many different ways. It is placed at the very beginning of the document and is read by each of Pandoc, Quarto and knitr. Along the way, the information that it contains can affect the code, content, and the rendering process.

Required Inputs

  • What editor should be the default for working in the document?
---
editor: visual
---


  • What format should the document render in?
---
format: html
---

A side-by-side comparison of how a Quarto document looks in the visual editor and the source editor.}

Code

Anatomy of a code chunk

```{r}
#| label: penguin-species
#| message: false

library(tidyverse)
library(palmerpenguins)

penguins |> 
  distinct(species)
```
# A tibble: 3 × 1
  species  
  <fct>    
1 Adelie   
2 Gentoo   
3 Chinstrap
  • Has 3x backticks on each end
  • Engine (r) is indicated between curly braces {r}
  • Options stated with the #| (hashpipe): #| option1: value

Different from RMarkdown formatting!

Notice the options here are not inside the {} but inside the code chunk! Where previously we had:

{r, echo = FALSE, message = FALSE, fig.align = "center"}

now we have:

{r}
#| echo: false
#| message: false
#| fig-align: center

Text

Text Formatting

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read


# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

Text Formatting


Markdown Syntax Output 
*italics* and **bold**
 italics and bold 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Headings

Markdown Syntax Output 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

 
##### Header 5
Header 5
 
###### Header 6
Header 6

Lists

Unordered list:

Markdown:

-   unordered list         
    -   sub-item 1         
    -   sub-item 1         
        -   sub-sub-item 1

Output

  • unordered list
    • sub-item 1
    • sub-item 1
      • sub-sub-item 1

Ordered list:

Markdown:

1. ordered list            
2. item 2                  
    i. sub-item 1          
         A.  sub-sub-item 1

Output

  1. ordered list
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1

Your turn!

Using the visual editor, add the following to your Quarto document:

  • A title
  • Your name as the author
  • Two new sections
    • One with fact you want to learn
    • One with your favorite thing about R

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 the render process.


There are a few different ways to render a Quarto file:

  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:
quarto::quarto_render("document.qmd") # defaults to html
quarto::quarto_render("document.qmd", output_format = "pdf")

Your turn!

  • With the Quarto document you have open
  • Render your document using the RStudio > Render button
  • Then compare the behavior of rendering with either
    • the terminal using quarto render or
    • the R console via quarto::quarto_render()

Additional YAML Options


---
format: 
  html:
    code-fold: true
---


Notice!

  • html: is now on a new line

  • this line is below format: and indented

  • the HTML formatting options are on their own line

  • these lines are below html: and indented

Your turn!

The exhaustive list of YAML options that can be used for HTML documents can be found here: https://quarto.org/docs/reference/formats/html. You can also get a drop down menu of all possible YAML options by hitting Try Ctrl + space.


Using this resource add the following to your document:

  • code folding
  • a table of contents
  • is self-contained
  • all figures are center aligned
  • no messages wan execution option which suppresses messages output from R

Afterward, add at least one additional YAML option of your choosing!





USCOTS Quarto Workshop