Experimenting with Quarto

Quarto is the up-and-coming “next generation version of R Markdown” being developed by RStudio. It’s more or less a superset of R Markdown/knitr that’s suited to programming languages besides R. Quarto’s heading towards a 0.1, and I’ve started experimenting for a few client projects.

So far I like the system a lot, and at this point I really think Quarto’s worth a try; especially since it’s available with the recent versions of RStudio.

This post lists a few of my favorite elements after a couple weeks’ using the tool off and on.

It’s built on RMarkdown

Because Quarto uses knitr to execute R code, my usual workflows don’t change unless I want them to. It’s just about all upside so far, and I’ve been able to use the old-style knitr::opts_chunk$set() syntax in places I haven’t been able to configure Quarto immediately.

YAML metadata for documents and chunks

Quarto takes the YAML metadata styling used by R Markdown (and pandoc and many other tools) and extends it. In particular, Quarto introduces some special syntax (#| key: value) to specify chunk-level options. This is supposed to replace the old style, where the options are crammed into the language identifier ({r title, fig.asp=0.618, ...}), and it’s particularly nice to specify a good number of options—like I might when building a figure:

  ```{r}
  #| label: my-figure
  #| fig-asp: 0.618
  #| fig-cap: |
  #|   This is a caption for my figure, 
  #|   using YAML formatting, etc.

  ggplot() + ...
  ```

Bootstrap layouts and styling

One of the nicest new features is the upgraded styling. First, the default theming feels much nicer than the old RMarkdown style (even if the default size is a little big for my taste). Second, though, the new styling makes margin notes easily possible and subfigures much easier to compose.

Margin notes are a big deal and can be enabled by switching reference-location: margin in the YAML front matter.

In the past I’ve relied on R4DS’s figures guidance for composing multiple figures in one chunk. But now Quarto can do this composition immediately using layout options, and, with the additional column: options, we can tell Quarto to expand the content width as we like. E.g., for two subfigures stretching across the page and outside of the normal body content block:

  ```{r}
  #| label: my-figure
  #| layout-ncol: 2
  #| column: page

  ggplot() + ...
  ggplot() + ...
  ```

It’s just so nice.

Preview mode

Quarto can be downloaded or built into a standalone application, it isn’t dependent on RStudio or any IDE. Using the command line tool, we can call quarto render to compile a document or we can call quarto preview to render a live preview that automatically updates when the source files are saved. This is exposed in RStudio via “Render on Save,” but it’s available in any editor using the command-line tool.

RStudio and VS Code integrations

Finally, there are the IDE integrations. When I’m working with R I’m almost always using RStudio, and RStudio has the expected set of built-in niceties. Mostly, these are all the usual knitr-powered switches, buttons, and keyboard shortcuts, but there is also editor completion for the various YAML configurations at the cell and editor level.

Just about all the work I do outside of R is handled with VS Code and, often, its Remote SSH and Remote Containers extensions. I’ve so far used Quarto less with VS Code than with RStudio, but I’ve already experimented with one nice feature: Quarto’s ability to render VS Code .ipynb documents (for which VS Code has a very nice integrated experience) as Quarto documents. This seems to work just like one would expect: Simply put the relevant YAML metadata in the top notebook cell and add #| key: value comments to blocks as necessary. VS Code renders and executes the notebook just as expected, and Quarto takes the notebook—and any output that’s been generated—and renders it like I’d expect if I’d written the code in R rather than Python.

This post is kindly republished by R-bloggers.