From rmarkdown to quarto to produce documents

Enhancing scientific publishing through Quarto

Christophe Dervieux

Posit

July 8, 2024

Get started with Quarto!

Let’s do it together! Follow along…

Create a Quarto project in RStudio and produce HTML.

• RStudio IDE
• Quarto CLI

File > New Project…

$ quarto create project
 ? Type » default
 ? Directory » quarto-101
Creating project at C:\Users\chris\AppData\Local\Temp\quarto-101:
  - Created _quarto.yml
  - Created quarto-101.qmd

Let’s explore…

quarto-101
L¦¦ quarto-101.qmd
L¦¦ _quarto.yml

_quarto.yml

project:
  title: "quarto-101"

quarto-101.qmd

---
title: "quarto-101"
---

## Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

Producing HTML

New button for transforming your document in RStudio IDE

terminal

quarto render quarto-101.qmd # defaults to html
quarto render quarto-101.qmd --to html

Producing HTML

What about my existing documents?

Convert from .Rmd to .qmd ?

No need, Quarto is compatible!

terminal

quarto render my-favorite.Rmd --to html

Over to you!

02:00

Add to the project

1. Create a sub-folder in the project e.g. reports.
2. Add the .Rmd exercise file named penguins.Rmd as is.
3. Generate HTML with quarto preview reports/penguins.Rmd in Terminal.
4. Generate HTML using the Render button in the IDE.

Display the Render button instead of Knit for an Rmd in a Quarto project

Remove output: html_document from the YAML header and save the file: The Render button should now appear.

From .Rmd to .qmd.

Let’s see what changes!

YAML header for Metadata

YAML is still used to provide document-level metadata.

---
title: "A penguin story"
author: "C. Dervieux"
date: "2024-07-08"
format: 
  html: 
    toc: true
---

• Some general metadata informations for the document

• Some format specific configuration for the targetted output format

YAML for cells options

```{r species, warning=FALSE, fig.width=5, fig.cap="About penguins"}
ggplot(
  penguins,
  aes(
    x = bill_length_mm, y = bill_depth_mm,
    color = species, shape = species
  )
) +
  geom_point() +
  labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

YAML for cells options

```{r}
#| label: species
#| fig-width: 5
#| fig-cap: About penguins
ggplot(
  penguins,
  aes(
    x = bill_length_mm, y = bill_depth_mm,
    color = species, shape = species
  )
) +
  geom_point() +
  labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

YAML for cells options

#| label: species
#| fig-width: 5
#| fig-cap: About penguins

Quarto introduces the “hash pipe” in #| - this is the preferred syntax, although Quarto is backwards compatible with the old R Markdown syntax.

1. Consistency between computation engines (Jupyter/knitr/julia)
2. Consistency between YAML header / YAML in cells / Divs options (:::)
3. One option per line, offering autocompletion and validation

Note

Technically, this is constructed as <language-comment-char>| e.g. # for R, Python and Julia but //| for OJS cells as // is the comment char for Javascript.

YAML for cells options

#| fig-width: 5
#| fig-cap: About penguins

Note that YAML for Quarto will follow a “word-word” syntax, with a - dash and not a ..

The difference in syntax is due to the fact that Quarto is more closely aligned with Pandoc’s format names and options (hence the use of - as a word separator instead of _ or .).

Over to you!

05:00

Transform into .qmd

1. Copy penguins.Rmd to new-penguins.qmd.
2. Use knitr::convert_chunk_header() on .qmd file
   1. see function help ?knitr::convert_chunk_header() to know how to use it
3. Check code cells configurations
4. Check YAML header of .qmd file
5. Produce HTML document in .qmd format

New Quarto features

You can test YAML autocompletion and validation in RStudio IDE 🔗

Quarto unifies R Mardown

Let’s look at Quarto’s built in features!

Callout Blocks

R Markdown	Quarto
Custom Blocks of rmarkdown and bookdown to create and style yourself.	Callout Blocks available in all formats and already styled.

::: {.callout-note}

## About callouts

Note that there are five types of callout:
`note`, `warning`, `important`, `tip`, and `caution`.
:::

About callouts

Note that there are five types of callout: note, warning, important, tip, and caution.

References(Figures, Tables, …)

R Markdown	Quarto
Available with bookdown in “book” formats (e.g. gitbook()) or single document variants such as html_document2()	Cross References available in all formats, for more content and configurable.

Change of syntax!

• Prefix required on the label in the form fig- and not fig:
• Same syntax as quote with @label and not \@ref(label)

See @fig-quarto-schematic for Alison Horst's illustration of how Quarto works.

![An illustrated diagram of Quarto](images/quarto-schematics.png){#fig-quarto-schematic}

References (Figures, Tables, …)

See @fig-quarto-schematic for Alison Horst's illustration of how Quarto works.

![An illustrated diagram of Quarto](images/quarto-schematics.png){#fig-quarto-schematic}

See Figure 1 for Alison Horst’s illustration of how Quarto works.

Figure 1: A schematic representing rendering of Quarto documents from .qmd

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

Article Layout

R Markdown	Quarto
Available for HTML with distill (Figure layout) ou tufte (Margin content)	Article Layout available for multiple formats and with more flexibility.

Beware of distill to Quarto conversion due to option conflicts!

Over to you!

15:00

Add these features!

In your new-penguins.qmd document:

• Try adding the following features:
  • Article Layout,
  • Cross References (Figures, Tables, or any others…),
  • Callout Blocks.
• See how to add layouts for figures created from code (Figure computation).
• And much more in the Authoring section of the guide. Curious about Quarto’s unique features?
  • Code Annotation
  • Built-in Diagram renderers

Note

You can start from your previous document, or download a fresh version from Tutorial’s website

Quarto formats

As with R Markdown, different document formats can be produced.

Multiple formats…

• format: html
• format: pdf

• format: typst
• format: docx

• format: revealjs
• format: pptx

format: 
  html:
    code-fold: true
  pdf:
1    lof: true
2toc: true

1

lof = List Of Figures

2

Example of an option common to HTML and PDF formats

…based on Pandoc

Specific options - Ex: HTML Themes

Quarto’s HTML is styled with Bootstrap 5 and default values chosen for Quarto.

---
format:
  html:
    theme: litera
---

Specific Options - Ex: HTML Themes

Quarto’s HTML is styled with Bootstrap 5 and default values chosen for Quarto.

---
format:
  html:
    theme: 
      - litera
      - custom.scss
---

You can also use a theme and customize components with SCSS/SASS.

Specific options - Ex: Code tools

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

Discover the options!

• Quarto guide: https://quarto.org/docs/guide/

• Options reference pages for each format: https://quarto.org/docs/reference/

• YAML auto-completion: https://quarto.org/docs/tools/rstudio.html#yaml-intelligence

My turn!

Demo time ! 🕙

Produce a PDF

• Little or no change in the .qmd used to produce HTML.

If you want to try…

You’ll need to be set up for LaTeX, but it’s not really suited to the tutorial context.

• PDF = LaTeX = TinyTeX installation
• LaTeX = CTAN packages => Long installation
• Producing a PDF with LaTeX => Not so fast

Your turn!

Produce a PDF with Typst

• Change to format: typst and Render. Look at your shiny new PDF !
• Learm more about Typst at in Quarto’s guide and tweak options.

Quarto 1.5 required

You really need latest Quarto 1.5 for our example to render completely.

10:00

Demo time ! 🕙

Questions ?

Now let’s take a look at how Quarto can be used to produce more sophisticated content.

Next