RStudio IDE

Overview

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 (v2023.12).

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

Creating Documents

Use the File : New File : Quarto Document… command to create new Quarto documents:

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 will appear alongside the editor:

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 you re-render the document. Side-by-side preview works for both HTML and PDF output.

Projects

If you want to create a new project for a Quarto document or set of documents, use the File : New Project… command, specify New Directory, then choose Quarto Project:

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.

Visual Editor

RStudio IDE includes a visual editor for Quarto markdown, including support for tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, and more:

To learn more, see the documentation on Using the Visual Editor with RStudio.

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

Note

Note that if you prefer it is still possible to include chunk options on the first line (e.g. ```{r, echo = FALSE}). That said, we recommend using the comment-based syntax to make documents more portable and consistent across execution engines.

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

Caution

the !expr syntax is an example of a YAML “tag” literal, and it can be unintuitive. !expr needs to be followed by a single YAML “flow scalar”: see the YAML spec for details on how double-quoted, single-quoted, and unquoted strings work.

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

If you want to work within a virtual environment (venv), use the File : New Project… command, specify the Jupyter engine with a venv, and specify which packages you’d like to seed the venv with:

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 render a website (ie; all qmd in a directory organized as a website):

library(quarto)
quarto_render()

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