GeezerVison

Overview

Quarto is a multi-language, next generation version of R Markdown from RStudio, with many new features and capabilities. Like R Markdown, Quarto uses Knitr to execute R code, and is therefore able to render most existing Rmd files without modification.

We’ll start by covering the basics of Quarto, then delve into the differences between Quarto and R Markdown in the sections on Chunk Options and Output Formats below.

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "5/22/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, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Installation

To use Quarto with R, you should install the rmarkdown R package:

install.packages("rmarkdown")

Installation of the rmarkdown package will also install the knitr package so you will have everything required to render documents containing R code.

Quarto will select a version of R by looking on the system PATH. In addition, on Windows when R is not found on the PATH, the registry will be scanned for the current R version. You can override the version of R used by Quarto by setting the QUARTO_R environment variable to the directory where the R binary RScript is.

RStudio

RStudio v2022.07 and later includes support for editing and preview of Quarto documents (the documentation below assumes you are using this build or a later version).

If you are using Quarto within RStudio it is strongly recommended that you use the latest release of RStudio.

You can download RStudio from https://posit.co/download/rstudio-desktop/.

Positron

The Quarto Extension is bundled with Positron, and provides a variety of tools for working with .qmd files. The extension integrates directly with Positron’s native R support to provide code completion, cell execution and side-by-side preview of Quarto documents.

The extension includes a Quarto: Preview command that can be accessed via the Command Palette, the keyboard shortcut , or a Preview button () in the editor toolbar. After rendering, a preview is displayed in the Viewer pane within Positron.

You can read more about using Positron in Tools: Positron.

VS Code

The Quarto Extension for VS Code provides a variety of tools for working with .qmd files in VS Code. The extension integrates directly with the R Extension to provide the following R-specific capabilities:

1. Code completion
2. Cell execution
3. Contextual help

You can install the VS Code extension by searching for ‘quarto’ in the extensions panel or from the extension marketplace.

The VS Code extension includes a Quarto: Preview command that can be accessed via the Command Palette, the keyboard shortcut , or a Preview button () in the editor. After rendering, a preview is displayed in a pane within VS Code alongside your document.

You can read more about using VS Code in Tools: VS Code.

Emacs

The quarto-mode MELPA package is an Emacs mode for editing Quarto documents. Install quarto-mode as follows:

M-x package-refresh-contents
M-x package-install
  quarto-mode

If you have ESS, quarto-mode will make use of it for executing R code.

Use M-x quarto-preview to start a quarto preview server that watches quarto content for changes and automatically refreshes it. If the current buffer has an associated file that exists in a quarto project, the command will preview the entire project. Otherwise, it will preview the specific file.

Chunk Options

One important difference between R Markdown documents and Quarto documents is that in Quarto chunk options are typically included in special comments at the top of code chunks rather than within the line that begins the chunk. For example:

```{r}
#| echo: false
#| fig-cap: "Air Quality"

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Quarto uses this approach to both better accommodate longer options like fig-cap, fig-subcap, and fig-alt as well as to make it straightforward to edit chunk options within more structured editors that don’t have an easy way to edit chunk metadata (e.g. most traditional notebook UIs).

Chunk options included this way use YAML syntax rather than R syntax for consistency with options provided in YAML front matter. You can still however use R code for option values by prefacing them with !expr. For example:

#| fig-cap: !expr 'paste("Air", "Quality")'

Chunk Labels

You can set a label for a code chunk with the label option:

```{r}
#| label: convert
airquality$TempC <- (5 / 9) * (airquality$Temp - 32)
```

Unless you want to specify a cross-reference avoid using the reserved cross-reference prefixes for chunk labels.

Conditional Execution

To execute a cell only for certain output formats, read the QUARTO_EXECUTE_INFO environment variable inside the cell. For example, you could execute code only if the target format is based on HTML (e.g. for html, revealjs, and dashboard formats):

```{r}
info <- jsonlite::fromJSON(Sys.getenv("QUARTO_EXECUTE_INFO"))
is_html <- info$format$identifier$`base-format` == "html"

if (is_html) {
  # HTML-only code, e.g. an interactive widget
}
```

This pairs well with conditional content when both visibility and execution should depend on format. See Execution Context Information for the full JSON schema.

For R cells using the knitr engine, knitr’s knitr::is_html_output(), knitr::is_latex_output(), and knitr::pandoc_to() predicates are also available for the common format-detection cases. See the knitr manual.

Output Formats

Another difference between R Markdown and Quarto is related to output formats. Quarto includes many more built in output formats (and many more options for customizing each format). Quarto also has native features for special project types like Websites, Books, and Blogs (rather than relying on external packages).

To use a format in Quarto you use the format key rather than the output key as you did in R Markdown. Here’s a comparison of equivalent format specifications:

R Markdown

title: "My Document"
output:
  html_document:
    toc: true
    number_sections: true
    css: styles.css

Quarto

title: "My Document"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css

One source of the difference in syntax is that Quarto is more closely aligned with Pandoc format names and options (thus the use of - as a word separator rather than _).

See the listing of all supported formats along with their user guides and reference pages for more details.

See the articles on creating Websites, Books, and Blogs for additional details on more advanced output formats.

Data Frames

You can control how data frames are printed by default using the df-print document option. Available options include:

For example, here we specify that we want paged printing for data frames:

---
title: "Document"
format: 
   html:
     df-print: paged
---

Knitr Options

If you are using the Knitr cell execution engine, you can specify default document-level Knitr chunk options in YAML. For example:

---
title: "My Document"
format: html
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true
---

You can additionally specify global Knitr options using opts_knit.

The R.options chunk option is a convenient way to define R options that are set temporarily via options() before the code chunk execution, and immediately restored afterwards.

In the example above, we establish default Knitr chunk options for a single document. You can also add shared knitr options to a project-wide _quarto.yml file or a project-directory scoped _metadata.yml file.

Caching

The Knitr Cache operates at the level of individual cells rather than the entire document. While this can be very convenient, it also introduced some special requirements around managing the dependencies between cells.

You can enable the Knitr cache at the document or project level using standard YAML options:

---
title: "My Document"
format: html
execute: 
  cache: true
---

You can also enable caching on a per-cell basis (in this you would not set the document level option):

```{r}
#| cache: true

summary(cars)
```

There are a variety of other cell-level options that affect Knitr caching behavior. You can learn about them in the Knitr cell options reference. Another excellent resource is Yihui Xie’s article on cache invalidation.

Terminal

# use a cache (even if not enabled in options)
quarto render example.qmd --cache 

# don't use a cache (even if enabled in options)
quarto render example.qmd --no-cache 

# use a cache and force a refresh 
quarto render example.qmd --cache-refresh 

---
title: "My Document"
format: html
execute: 
  enabled: false
---

execute:
  freeze: true  # never re-render during project render

execute:
  freeze: auto  # re-render only when source changes

Terminal

# render single document (always executes code)
quarto render document.qmd

# render project subdirectory (always executes code)
quarto render articles