Welcome to Quarto

From R Markdown to Quarto
rstudio::conf 2022

Andrew Bray

From R Markdown to Quarto

Welcome!

As you arrive, if you haven’t already, please get your machine configured using the steps found on the workshop website. Please assist your neighbors if they’re running into issues.

https://rstudio-conf-2022.github.io/rmd-to-quarto/materials/

Also, please be ready with Discord for discussions (you should have an invite in your email from the conference).

Introductions

Take ~2 minutes to introduce yourself to your neighbors.

Please share …

1. Your name
2. Where you’re from
3. What you work on in 3 words or fewer
4. Name one thing you’ve made that you’re proud of

About the Workshop

Workshop schedule, slides, and exercises are at:

rstd.io/rmd-to-quarto

Goals for the Workshop

1. Everyone leaves with a document, slides, and a website.

2. Learn from one another.

3. Build an understanding of the big picture.

From Magic to Magical Machines

Artwork by Allison Horst

Workshop Schedule

Day One

• 9-10:30 am Welcome to Quarto
• 10:30-11 am coffee break
• 11-12:30 pm Polishing Documents
• 12:30-1:30 pm lunch
• 1:30-3 pm Computations
• 3-3:30 pm coffee break
• 3:30-5 pm Projects and Publishing

Day Two

• 9-10:30 am Presentations
• 10:30-11 am coffee break
• 11-12:30 pm Websites and Books
• 12:30-1:30 pm lunch
• 1:30-3 pm Project Workshop
• 3-3:30 pm coffee break
• 3:30-5 pm The Future of Quarto

Discussions

Ask a question by opening a new discussion post:
https://github.com/rstudio-conf-2022/rmd-to-quarto/discussions

Stickies

During an exercise, place a yellow sticky on your laptop if you’re good to go and a blue sticky if you want help.

Polls

During polls, you can vote in a browser tab either on your laptop or your phone at

pollev.com/rmdtoquarto

Practicalities

• WiFi:
  • Username: conf22
  • Password: together!
• There are gender neutral bathrooms by the National Harbor rooms.
• The meditation room is located at National Harbor 9. Open 8am - 5pm, Monday - Thursday. The hotel also has a dedicated room behind the reception.
• The lactation room is located at Potomac Dressing Room. Open 8am - 5pm, Monday - Thursday.
• Participants who do not wish to be photographed have red lanyards, please note everyone’s lanyard colors before taking a photo and respect their choices.

Code of Conduct
Please carefully review the Code of Conduct and COVID policies¹ can be found at . Please review them carefully. RStudio requires that you wear a mask that fully covers your mouth and nose at all times in all public spaces. We strongly recommend that you use a correctly fitted N95, KN95, or similar particulate filtering mask; we will have a limited supply available upon request. You can report Code of Conduct violations in person, by email, or by phone. Please see the policy linked above for contact information.

1. https://www.rstudio.com/conference/2022/2022-conf-code-of-conduct/

What can you do with Quarto?

Articles

Presentations

Websites

Books

Quarto and R Markdown

Quarto and R Markdown, a history . . .

• 1984 Literate Programming proposed to combine text with code
• 2002 Sweave weaves together S/R and \(\TeX\)
• 2006 pandoc converts between different document formats
• 2012 knitr a next gen Sweave for R and Markdown
• 2014 knitr::pandoc added to leverage pandoc flexible outputs
• 2015 pandoc functionality moved into new rmarkdown
• 2018 R Markdown: A definite guide
• 2020 R Markdown Cookbook

. . . throughout, an ecosystem of R packages develops . . . (bookdown, blogdown, distill, etc.)

How is Quarto Different than R Markdown?

1. Quarto is compute-agnostic. R Markdown requires R.

2. The ecosystem of R packages is replaced by a single framework.

What can you do with R Markdown that you can’t with Quarto?

• Access tools built around R Markdown (e.g. blogdown, xaringan, workflowr, papaja) that haven’t yet been implemented in Quarto.

Heavy users of such tools may want to stick with R Markdown.

What can you do with Quarto that you can’t with R Markdown?

• Easier to organize appearance across documents
• Features (e.g. figures, tables) have better cross-format support
• Better cross referencing
• Up-to-date revealjs slides
• Easier to customize websites and books with projects

Exercise 0

Let’s kick the tires on Quarto!

1. Open up a new Quarto document using an HTML format

2. Click the Render button.

3. Look carefully through the source. What do you notice that’s different from what it would look like in an Rmd document? Discuss with your neighbor then post your answers to the discussion forum.

Rendering in Quarto

Inputs

Outputs

Quarto Render

Render input file to various document formats.

Input

• *.qmd
• *.ipynb
• *.md
• *.Rmd

Format

• html
• pdf
• revealjs
• docx
• ppt
• and many more!

Three ways to render

1. Quarto is integrated into RStudio

   Click in Editor pane of RStudio.

2. Quarto is an R package

   Run in R:

   quarto::quarto_render(input = ___, output_format = ___)

3. Quarto is a command line tool

   Run at the terminal:

   quarto render <input> --to <format>`

Getting Exercise

To get the materials for each part of this course packed in an RStudio Project, run:

```{r}
usethis::use_course("rmd-to-quarto/welcome-to-quarto")
```

You can also git clone if you prefer that workflow.

1. Navigate to the terminal tab of the console pane
2. Run quarto render demo.qmd –to html
3. Run quarto render demo.qmd –to docx
4. Run quarto render demo.qmd –to latex
5. Inspect how emphasis and the image is expressed

Element expression depends on format

Emphasis

HTML

A <em>spatial logical toy</em>

LATEX

A \emph{spatial logical toy}

Image

HTML

<img src="images/med-rubiks-cube.png" class="img-fluid">

LATEX

\includegraphics{images/med-rubiks-cube.png}

Exercise 1

Let’s focus on using quarto at the command line. Within RStudio, this can be done in the Terminal tab in the Console pane.

1. Render ex-1.qmd to html and view the html file in an editor. How is the list expressed in html?
2. Render ex-1.qmd to latex and view the latex file in an editor. How is the list expressed in latex?
3. Render ex-1.qmd to pdf but specify that you want to output to a file named handout.pdf. (see the helpfile for render by typing quarto render --help)
4. Try changing the extension of ex-1.qmd to be .md and .Rmd and re-rendering. Does the output differ?
5. Explore full list of commands available in Quarto by using quarto --help.

Try Pandoc!

A quick way to find out how Pandoc will convert: https://pandoc.org/try/.

The Structure of a Document

What Defines a Document?

A document consists of content, structure, appearance, format.

• Content: text, code, graphics
• Structure: paragraphs, lists, emphasis, etc.
• Appearance: fonts, colors, layout
• Format: functionality

What defines the structure of a document?

A document is a list of block elements that contain inline elements or other blocks, along with associated metadata.

A document is a list of block elements that contain inline elements or other blocks, along with associated metadata.

Block Element

Starts on a new line and followed by an empty line. Forms a visible block.

Block 1

Block 2

Block 3

Examples:

• Paragraph
• Heading
• Image
• List

A document is a list of block elements that contain inline elements or other blocks, along with associated metadata.

Inline Element

Modifies content inline and is not followed by a new line.

Block 1

Inline 1

Inline 2

Block 3

Examples:

• Emphasis
• Link
• Footnote
• Citation

A document is a list of block elements that contain inline elements or other blocks, along with associated metadata.

Metadata

Ancillary info about the document’s origin, format, look, etc.

Metadata

Block 1

Inline 1

Inline 2

Block 3

Examples:

• Author
• Keywords
• Character set
• Appearance/style

A document is a list of block elements that contain inline elements or other blocks, along with associated metadata.

Header

Paragraph

Emphasis

Image

The Elements of Markdown

• Markdown is designed to be easy to write, and, even more importantly, easy to read:

  A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
  -John Gruber

• Quarto uses extended version of Pandoc markdown designed with multiple output formats in mind.

Whenever I hear “Pandoc”, I picture . . .

. . . but there’s help!

Poll

Which of the following forms of text formatting are possible in pandoc markdown?

• italics
• bold
• underline
• superscript
• subscript
• strikethrough

Inline Elements: Text Formatting

Markdown

Markdown allows you to format text with 
*emphasis* and **strong emphasis**. You can 
also add superscripts^2^, subscripts~2~, and
display code `verbatim`. Little known fact:
you can also ~~strikethrough~~ text and 
present it in [small caps]{.smallcaps}.

Output

Markdown allows you to format text with emphasis and strong emphasis. You can also add superscripts², subscripts₂, and display code verbatim. Little known fact: you can also strikethrough text and present it in small caps.

1. Either the * or _ can be used for emphasis and strong.

Inline Elements: Math

Markdown

The area of a circle is $A = \pi r^2$,where
$r$ is the radius and $\pi$ is the constant
$3.141592\ldots$.

Output

The area of a circle is \(A = \pi r^2\), where \(r\) is the radius and \(\pi\) is the constant \(3.141592\ldots\).

TeX math lives between two $. Opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit.

Inline Elements: Links and Images

Markdown

You can embed [links with names](https://quarto.org/),
direct urls like <https://quarto.org/>, and links to 
[other places](#inline-elements-text-formatting) in 
the document. The syntax is similar for embedding an
inline image: ![render icon](images/render-icon.png).

Output

You can embed links with names, direct urls like https://quarto.org/, and links to other places in the document. The syntax is similar for embedding an inline image: .

Inline Elements: Footnotes

Markdown

Here is a short note.^[Small enough to fit inline.]

Output

Here is a short note.¹

Here is a longer footnote[^1]

[^1]: This footnote can be placed in a separate block.
The identifier can be any alphanumeric string.

Here is a longer footnote²

Placement of the actual footnote depends on the format: end of page for pdf, end of doc for HTML, bottom of slide for presentations.

1. Small enough to fit inline.

2. This footnote can be placed in a separate block. The identifier can be any alphanumeric string.

Block Elements: Paragraph

One or more lines of text followed by one or more blank lines.

Markdown

Lorem ipsum dolor sit amet,
consectetur adipiscing elit.

Sed do eiusmod tempor.

Output

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Sed do eiusmod tempor.

Without the blank line, the line break is treated as a space.

Lorem ipsum dolor sit amet, 
sconsectetur adipiscing elit.
Sed do eiusmod tempor.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor.

Block Elements: Headers

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

Block Elements: Lists

Can use *, -, or + may be used for unordered list items.

Markdown

Unordered list:

* red
* green
* blue

Ordered list:

1. red
1. green
3. blue

Output

Unordered list:

• red
• green
• blue

Ordered list:

1. red
2. green
3. blue

Pandoc gives you a lot of control over lists, including nesting, fancy lists, definition lists, blocks in lists, and example lists.

Read the docs for details: https://pandoc.org/MANUAL.html#pandocs-markdown

Poll

Which of the following will render to the output on the right?

A

1. I once has a sandwich.

   It was deliiiicous.
   
1. I then had coffee.

   It gave me joy.

C

1. I once has a sandwich.
It was deliiiicous.
   
2. I then had coffee.
It gave me joy.

B

1. I once has a sandwich.
  It was deliiiicous.
   
2. I then had coffee.
  It gave me joy.

D

1. I once has a sandwich.

    It was deliiiicous.
   
2. I then had coffee.

    It gave me joy.

Output

1. I once has a sandwich.

   It was deliiiicous.

2. I then had coffee.

   It gave me joy.

It’s hard to tell but there are two paragraphs in each list item in the output.

Block Elements: Lists (blocks in lists)

“A list item may contain multiple paragraphs and other block-level content. Subsequent block elements must be preceded by a blank line and indented to line up with the first non-space content after the list marker.”

Markdown

1. First item...

   ...Continued.

1. Second item 

   # header
   
1. Third item

Output

1. First item…

   …Continued.

2. Second item

   header

3. Third item

Block Elements: Lists (example lists)

“The first list item with a @ marker will be numbered 1., the next 2., etc. The numbered examples need not occur in a single list; each new list using @ will take up where the last stopped.”

Markdown

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).

Output

1. My first example will be numbered (1).
2. My second example will be numbered (2).

Explanation of examples.

3. My third example will be numbered (3).

You can also label your examples: (@goodname).

Block Elements: Math

Markdown

A larger equation:

$$ 
f(x)={\sqrt{\frac{\tau}{2\pi}}}
      e^{-\tau (x-\mu )^{2}/2}
$$



This breaks it:

$$

\bar{x} = \sum_{i=i}^n x_1
$$

Output

A larger equation:

\[ f(x)=\sqrt{\frac{\tau}{2\pi}} e^{-\tau (x-\mu )^{2}/2} \]

This breaks it:

$$

{x} = _{i=i}^n x_1 $$

For “display” math, use $$ delimiters. The delimiters may be separated from the formula by whitespace. No blank lines between the opening and closing $$ delimiters.

Block Elements: Images

Block images use the same syntax as inline images.

Markdown

Images on their own line become a block:

![Elephant](images/elephant.png)

or do they?

Output

Images on their own line become a block:

Elephant

or do they?

Images behave mostly like inline elements but often live in a dedicated block (e.g. a paragraph). Their behavior depends on output format.

Poll

Which of the following are valid ways to include metadata with a document?

A

---
title: US Patent: A Spatial Toy
author: Erno Rubik
format: html
---

My idea is to build a cube...

C

---
format: html
---

My idea is to build a cube...

---
title: A Spatial Toy
author: Erno Rubik
---

C

My idea is to build a cube...

… then at the command line, run:

quarto render patent.qmd --to html -M title:patent

D

---
title: "US Patent: A Spatial Toy"
author: "Erno Rubik"
format: "html"
---

My idea is to build a cube...

Metadata: YAML

Metadata can be included via YAML (YAML Ain’t Markup Language).

---
title: "US Patent: A Spatial Toy"
author: 
  - Erno Rubrik
  - Albert Einstein
format: 
  html:
    toc: true
    abstract: |
      This is the abstract.
    
      It has two paragraphs.
---

Some syntax rules:

• Set a single option key: value
• Strings with : must be quoted
• Include multiple values in a list with -
• Nest key-value pairs using indentation
• Multi-line strings follow |
• Multiple YAML blocks in a document will be merged

Pandoc’s interpretation of YAML metadata: https://pandoc.org/MANUAL%202.html#extension-yaml_metadata_block

An overview of YAML syntax: https://en.m.wikipedia.org/wiki/YAML#Syntax

Metadata: YAML

A

---
title: US Patent: A Spatial Toy
author: Erno Rubik
format: html
---

My idea is to build a cube...

C

---
format: html
---

My idea is to build a cube...

---
title: A Spatial Toy
author: Erno Rubik
---

C

My idea is to build a cube...

… then at the command line, run:

quarto render patent.qmd --to html -M title:patent

D

---
title: "US Patent: A Spatial Toy"
author: "Erno Rubik"
format: "html"
---

My idea is to build a cube...

Exercise 2

Inside ex-2.qmd you’ll find all of the content needed to create the output files ex-2-goal.html and ex-2-goal.pdf. Add into ex-2.qmd the markdown syntax needed to create the various inline and block elements found in the output documents.

Inline

• text formatting
• math
• links and images
• footnotes

Block

• paragraphs
• headers
• lists
• math
• images

For reference, see: https://pandoc.org/MANUAL.html#pandocs-markdown

References and further reading

• A Brief History of R Markdown: a presentation by Yihui Xie in 2021.
• Pandoc documentation on type references: this section documents the tools needed to write Lua filters but included in this is a compendium of the different block and inline elements recognized by pandoc.
• Block and Inline Elements: from Client-side Web Development by Ross and Freeman. Provides clear description of elements in the setting of HTML.
• Command Line Essentials: a short primer on how to navigate through a file structure at the command line.sla
• Spatial Logical Toy: The US patent of what became the Rubik’s Cube. Several examples in these slides borrow figures and text from the patent.