I'm an R user: Quarto or R Markdown?

Earlier this year, Posit (formerly RStudio) released Quarto. Quarto is an open-source scientific and technical publishing system that allows you to weave together narrative text and code to produce high-quality outputs including reports, presentations, websites, and more.

One of the main features of Quarto is that it isn’t just built for R. It’s language-agnostic. It can render documents that contain code written in R, Python, Julia, or Observable. That makes it incredibly useful if you work in multilingual teams, or collaborate with people who write in a different programming language from you. But what if you don’t use any other programming languages? What benefits does Quarto bring to people who only use R?

In this blog post, we’ll highlight some of the features of Quarto that R users might benefit from.

Command Line Interface

Unlike R Markdown, Quarto isn’t an R package.* Quarto is a command line interface. This makes it much easier to work with Quarto documents outside of the RStudio IDE. For example, if you ever need to render a file from a terminal, we think you’ll agree that quarto render document.qmd is a lot more user-friendly than:

Rscript -e "rmarkdown::render('document.Rmd')"

To see the other command line options, run quarto --help in the terminal.

* Although Quarto itself isn’t an R package, there is a package called {quarto} that provides an R interface to frequently used operations in the command line interface. Installing the R {quarto} R package, doesn’t install quarto itself - {quarto} is just a thin wrapper to actual application.

Quarto is a single product

In R Markdown, you might use {distill} to build a website, {bookdown} to write a book, and {revealjs} to make slides. That might mean you’re using three different packages to create three different types of content on the same topic. Quarto combines the functionality of R Markdown, bookdown, distill, and other packages into a single system. This can make it easier to create content with multiple outputs formats. For example, you can use cross-references without installing {bookdown}, and make presentations without installing {revealjs}. Having fewer dependencies makes projects easier to maintain in the longer term - you don’t have as many R packages to update!

Combining content (and shortcodes)

Quarto allows you to use Hugo style includes. This gives a convenient way of reusing content across multiple documents. For example, suppose you have a paragraph or two that provides an introduction to your company. Instead of constantly copying and pasting, the paragraph is stored in a separate document, about.qmd, and can be included using {{< include about.qmd >}}. Adding this snippet to your document is the equivalent to copying and pasting the text from about.qmd into the main file. The consequence is that relative links/images are resolved based on the directory of the main document.

include is just one example of a quarto shortcode. Other useful shortcodes to note, is the var and pagebreak. The var shortcode, allows you to access values from the _variables.yml file. In the past, you might have written a short R function for this task. The pagebreak shortcode gives a convenient mechanism for adding page breaks in different output formats, e.g. HTML, pdf, or doc.

You can write your own shortcode and distribute it as an extension. This looks interesting, but so far, relatively few extensions have been created. One reason is that you need to learn Lua to write one.

Extensions

Speaking of Quarto extensions… Shortcodes are just one element that can be shared as a Quarto extension. You can also create custom templates for different types of documents. For example, adding corporate branding to a PDF report. Previously, you may have stored these templates as part of an R package. Although you can still share custom Quarto templates as part of R package, sharing it as a Quarto extension instead means you don’t have to build an R package just to share a template. It also not only means that non-R users can use your template - it means you don’t need to use R if you’re making a presentation that doesn’t include any R code.

There are a number of templates shared publicly including templates for academic journal formatting. If you need to change the layout of an article to re-submit it to a different journal, it’s as simple changing jss-pdf to jasa-pdf. The Awesome Quarto GitHub repository has a list of extensions and templates created by the Quarto community.

Quarto Projects

Quarto projects are directories that provide a way to render all (or some) of the files in a directory at the same time. For example, chapters in a book or pages in a website. A huge benefit of Quarto projects, is the existence of the _quarto.yml file. This file gives you the ability to share YAML metadata options across multiple documents - including format-specific options. You can store metadata that differs depending on whether you render a document as HTML or PDF, in a single place.

Another file that can be shared across files in your project directory is the _variables.yml file. This allows you to insert content from the _variables.yml file into using the var shortcode. For example, you may include information on your company’s email address on different pages of your website.

email:
  info: hello@jumpingrivers.com

You can then access this and add it to a page using {{< var email.info >}}. If your email address changes, you don’t need to update it on every page on the website - you just need to update the _variables.yml file. This feels like a really nice way of sharing information across multiple documents.

Global code block options

When you want to set code chunk options in R Markdown that apply to your whole document, you need to include a set up code chunk at the top of your document.

```{r}
knitr::opts_chunk$set(echo = FALSE)
```

In Quarto, rather than a writing a separate set up code chunk, you specify your document-wide options in the YAML at the start of the document. When you combine this with the YAML auto-completion feature, it makes it a lot easier to set document-wide options.

---
title: "A very cool title"
format: html
execute:
  echo: false
---

One of the execution options we really like is freeze. Setting freeze: true denotes that a document should never be re-rendered during a global project render, and setting freeze: auto only re-renders a document when its source file has changed. This is really useful if, for example, you write blog posts - you don’t necessarily want to re-run and update old blog posts every time you update your website. You can freeze them instead.

The other code block option we appreciate is the new fenced option for echo. The echo argument determines whether or not the code is shown in your output. When you set echo: fenced it shows the code block options as well as the code. It’s not something we use every day - but it’s very useful when you’re teaching someone else how to use Quarto!

It’s important to remember that R Markdown will continue to be maintained and supported so you don’t have to switch to Quarto. However, if you’re an R user considering changing over from R Markdown to Quarto, hopefully this blog post has highlighted some of the features you’ll gain from doing so.