---
title: "Quarto Integration"
date-meta: 2022-12-12
---

RStudio v2022.07.1 and later includes support for editing and preview of [Quarto documents](https://quarto.org/).

> Quarto^®^ is an open-source scientific and technical publishing system built on [Pandoc](https://pandoc.org/)
>
> -   Create dynamic content with [Python](https://quarto.org/docs/computations/python.html), [R](https://quarto.org/docs/computations/r.html), [Julia](https://quarto.org/docs/computations/julia.html), and  [Observable](https://quarto.org/docs/computations/ojs.html).
>
> -   Author documents as plain text markdown or [Jupyter](https://jupyter.org/) 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:

![](images/new-quarto-doc.png){fig-alt="The 'New Quarto Document' dialog menu in RStudio."}

## Render and Preview

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

![](images/rstudio-render.png){fig-alt="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:

![](images/rstudio-preview.png){fig-alt="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.

![](images/quarto-preview-control.png){fig-alt="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**, will show markdown images and formatted equations in the editor
- **Show Previews Inline**, when selected, outputs will be shown underneath the corresponding markdown, otherwise pop-ups will be shown when hovering over the markdown

#### 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](../tools/jobs.html) 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

![](images/quarto-job.png){fig-alt="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**

![](images/rstudio-new-knitr-project.png){fig-alt="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](https://quarto.org/docs/websites/) and [books](https://quarto.org/docs/books/). Options are also provided for creating a [git](https://git-scm.com/) repository and initializing an [renv](https://rstudio.github.io/renv/) environment for the project.

## Knitr engine

Quarto is designed to be highly compatible with existing [R Markdown](https://rmarkdown.rstudio.com/) 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:

``` yaml
#| 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:

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

To work within a virtual environment ([venv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)):

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:

![](images/rstudio-new-jupyter-project.png){fig-alt="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:

![](images/rstudio-pip-install.png){alt="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:

![](images/rstudio-yaml-completion.png){alt="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:

![](images/rstudio-yaml-diagnostics.png){fig-alt="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](https://quarto-dev.github.io/quarto-r/) R package. To install the R package:

``` r
install.packages("quarto")
```

Then, to render a document:

``` r
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:

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

If you are working on a [website](https://quarto.org/docs/websites/) or [book](https://quarto.org/docs/books/) project, you can also use `quarto_preview()` on a project directory:

``` r
library(quarto)
quarto_preview()
```
