Making your first webR-powered Quarto document

Author

James Joseph Balamuta

Published

March 20, 2023

Modified

July 1, 2024

To get started, we highly recommend watching our walkthrough video. This video provides an in-depth breakdown of how to use a Quarto extension like quarto-webr within a Quarto document. Following that, delve into the subsequent sections that highlight crucial workflow changes for incorporating webR functionality into your Quarto HTML documents. We strongly encourage you to bookmark this page, as it serves as an invaluable reference for users of all expertise levels.

Workflow Video

Installation

To use this extension in a Quarto project, install it from within the project’s working directory by typing into Terminal:

quarto add coatless/quarto-webr

Demonstration of using the Terminal tab to install the extension.
Note

Quarto extensions are project-specific installations and are not stored in a global library, unlike R packages. This means that for every new Quarto project or directory where you create a Quarto Document, you’ll need to install the extension again.

Usage

Once the extension is successfully installed, you can begin utilizing it in your Quarto documents located within the same working directory as the _extensions folder. To activate the webR functionality in those documents, follow these steps:

  1. Add webr Filter: In the header of your Quarto document, add the webr filter to the list of filters:
filters:
  - webr
  1. Use {webr-r} Code Blocks: Write your R code within code blocks marked with {webr-r}. Here’s an example:
---
title: webR in Quarto HTML Documents
format: html
engine: knitr
filters:
  - webr
---

This is a webr-enabled code cell in a Quarto HTML document.

```{webr-r}
fit = lm(mpg ~ am, data = mtcars)
summary(fit)
```
  1. Render Your Document: You can now render your Quarto document by clicking on Render (or use the keyboard shortcut ⇧⌘K on macOS or Ctrl+Shift+K on Windows/Linux). The document will execute under engine: knitr by default, but you can specify a different engine if needed.
Note

If an engine is not specified, Quarto will attempt to use the jupyter compute engine by default. This may cause an error if jupyter is not installed on your computer.

Fin

In summary, this guide has provided an overview of how to incorporate the community quarto-webr extension into your Quarto HTML documents using RStudio. We began with a walkthrough video that offered an in-depth understanding of how this Quarto extension operates within the Quarto framework. Subsequently, we explored key workflow changes necessary for incorporating webR into your Quarto HTML documents, from installation to document rendering.

For your next steps consider looking at different use cases for interactive options.

If you’re eager to delve even deeper, explore topics like setting document-level customizations inside the document header, using R packages inside webR, or hiding and executing code. These resources will further empower you to make the most of quarto-webr and webR to elevate your Quarto documents to new heights.

Important

This Quarto extension is open source software and is not affiliated with Posit, Quarto, or webR. The extension is at best a community effort to simplify the integration of webR inside of Quarto generated documents.