Quarto Integration

RStudio v2022.07.1 and later includes support for editing and preview of Quarto documents.

Quarto® is an open-source scientific and technical publishing system built on Pandoc

  • Create dynamic content with Python, R, Julia, and Observable.

  • Author documents as plain text markdown or Jupyter notebooks.

  • Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.

  • Author with scientific markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more.

If you are using Quarto within RStudio, it is strongly recommended that you use RStudio v2022.07.1 or a later version (the documentation below assumes you are using this build or later).

Installing Quarto

A stable release of Quarto is bundled with RStudio v2022.07.1, and later. Upgrading to new versions of RStudio in the future will also upgrade the bundled Quarto version.

To upgrade Quarto out of sync with the bundled version in RStudio, follow the directions at https://quarto.org/docs/download/

Creating new documents

Use the File > New File > Quarto Document command to create new Quarto documents, which will launch the New Quarto Document wizard:

The 'New Quarto Document' dialog menu in RStudio.

Render and Preview

Use the Render button to preview documents as you edit them:

The top section of a qmd file as displayed in RStudio. There is a toolbar right above the document containing various options, including 'Render.' There is a stylized, segmented blue arrow pointing at the word.

If you prefer to automatically render whenever you save you can check the Render on Save option on the editor toolbar.

The preview appears alongside the editor in the Viewer pane if Preview in Viewer Pane is selected:

An RStudio window. On the left half of the page is a Quarto document and the 'Jobs' pane open underneath that. There is messages in green text in the 'Jobs' pane that say: 'Watching files for changes. Browse at http://localhost:4064'. On the right half of the window is the Quarto output of the document on the left, as rendered by Knitr.

The preview will update whenever document is re-rendered. Side-by-side preview works for both HTML and PDF output.

Controlling output and preview

RStudio provides a dropdown menu to control the format options, such as the display location of preview renders, visual content such as tables and graphics, and raw text output from code.

Screenshot of the 'Gear' menu dropdown for controlling format options of a Quarto document.

Control location of rendered preview

Select one of the three following options:

  • Preview in Window, opening in the default browser
  • Preview in Viewer Pane, displaying the entire document preview in the Viewer Pane
  • (No Preview), there will not be a preview displayed when rendering

Control preview of markdown output

Select or deselect one of the following options:

  • Preview Images and Equations
  • Show Previews Inline

Control output of code chunks

Turn the following features on or off:

  • Chunk Output Inline, code output including graphics, tables, and printed output will display inline in the source document
  • Chunk Output in Console, code output will display in the console, graphics and tables in the Viewer pane

Quarto Background Job

Quarto documents are primarily rendered in RStudio with the Render button or the Render on Save option. Both of these options render the document within a Background Job which maintains a background preview web server. This provides a fresh R session for the rendered document along with a consistent URL to access the preview content.

To access and control the Quarto render, navigate to the Console pane and select the Background Jobs tab:

  • The duration of the current preview web server is available in the upper-right corner
  • Metadata, arguments, and output from the render process are printed and updated for each render
  • The URL to the preview web server is printed at the bottom of the output
  • To interrupt the render, press the red Stop button in the upper-right corner of the Background Jobs tab

A screenshot of the Background Jobs tab in RStudio, displaying the output of a Quarto render.

Projects

To create a new project for a Quarto document or set of documents:

  1. Use the File : New Project… command
  2. Specify New Directory
  3. Select Quarto Project

A section of the 'New Project Wizard' menu from Rstudio. This section is titled 'Create Quarto Project'. The Quarto logo is displayed on the left. ON the right are fields for 'Type', 'Directory name', and 'Create project as subdirectory of:'. Underneath that are options for 'Engine', 'Create a git repository', and 'Use renv with this project'. The option for 'Engine' is set to 'Knitr'. There are buttons for 'Create Project' and 'Cancel' arranged side-by-side in the bottom right of the window. There is an option to 'Open in new session' in the button left corner.

You can use this UI to create both vanilla projects as well as websites and books. Options are also provided for creating a git repository and initializing an renv environment for the project.

Knitr engine

Quarto is designed to be highly compatible with existing R Markdown documents. You should generally be able to use Quarto to render any existing Rmd document without changes.

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")

Jupyter engine

You can also work with Quarto markdown documents that target the Jupyter engine within RStudio. These files will typically include a jupyter option in the YAML front matter indicating which kernel to use. For example:

---
title: "Matplotlib Demo"
author: "Norah Smith"
jupyter: python3
---

To work within a virtual environment (venv):

  1. Use the File : New Project… command
  2. Specify the Jupyter engine with a venv
  3. Specify which packages you’d like to seed the venv with:

A section of the 'New Project Wizard' menu from Rstudio. This section is titled 'Create Quarto Project'. The Quarto logo is displayed on the left. ON the right are fields for 'Type', 'Directory name', and 'Create project as subdirectory of:'. Underneath that are options for 'Engine' and 'Kernel'. The option for 'Engine' is set to 'Jupyter,' and the option for 'Kernel' is set to 'Python 3'. Underneath these are options for 'Create a git repository', and 'Use venv with this project'. The button for 'Use venv...' is selected, and there is a text box to the right with the Python package names 'matplotlib' and 'pandas' filled in. There are buttons for 'Create Project' and 'Cancel' arranged side-by-side in the bottom right of the window. There is an option to 'Open in new session' in the button left corner.

RStudio will automatically activate this virtual environment whenever you open the project. You can install additional Python packages into the environment using the RStudio Terminal tab. For example:

An RStudio terminal window. The prompt is prefixed by the word '(env)', indicating that this prompt is taking place in a Python virtual environment named 'env.' The first line is empty and the second line contains the command 'python3 -m pip install scikit-learn.'

YAML intelligence

YAML code completion is available for project files, YAML front matter, and executable cell options:

Quarto document with YAML being edited. Next to the cursor code completion helper is open showing YAML options beginning with the letters preceding the cursor ('to').

If you have incorrect YAML it will also be highlighted when documents are saved:

Quarto document YAML metadata with an incorrect option underlined in red.

R package

If you are not using RStudio and/or you prefer to render from the R console, you can do so using the quarto R package. To install the R package:

install.packages("quarto")

Then, to render a document:

library(quarto)
quarto_render("document.qmd")

To live preview (automatically render & refresh the browser on save) for a document you are working on, use the quarto_preview() function:

library(quarto)
quarto_preview("document.qmd")

If you are working on a website or book project, you can also use quarto_preview() on a project directory:

library(quarto)
quarto_preview()