R Markdown has been one of the more compelling aspects of the R ecosystem, making it easy to combine results of R code with text to tell stories with data in a reproducible workflow. Plus, R Markdown files can be exported to a variety of formats—Word, HTML, PDF, PowerPoint, and more. You can even export complete books and websites.
But R Markdown has been around for 10 years. And as more capabilities were added via external R packages, syntax for basic tasks became inconsistent depending on, for example, whether output was a stand-alone HTML document, HTML slide presentation, or something else. Plus, while you could run additional languages besides R within an R Markdown code chunk, it still was fundamentally built for R.
Those are two of the reasons RStudio has developed Quarto, a next-generation, R Markdown-like publishing system. Quarto is open source, and it’s as friendly to Python, Julia, Observable JavaScript, and Jupyter notebooks as it is to R. It’s not a language-specific library, but an external software application.
After a soft launch of several months, Quarto was a major theme of this year’s RStudio Conference in late July.
Why bother with Quarto?
If you use more than one language, or you are on a multi-language team, you will likely find Quarto’s native support for multiple languages appealing. The “high internal consistency” is another attraction, as the same syntax will work across more languages and formats.
"Quarto enables collaborating across coding languages," Julia Stewart Lowndes, founder and co-director at Openscapes, said during an RStudio Conference keynote. Openscapes worked with NASA as early Quarto beta testers and found that Quarto made it much easier for Python and R users to work together, she said.
But one of the most intriguing benefits is down the road. RStudio founder and CEO J.J. Allaire envisions cloud-based collaboration for Quarto documents that will work the same way Google Docs editing does now—seamlessly and without users needing to explicitly use an external version control tool like Git. However, Allaire stressed that this functionality is not imminent.
For now, though, Quarto was designed to work equally well in Visual Studio Code and Jupyter as it does in RStudio, which the company hopes will make adoption among teams with non-R users more likely. In fact, those doing mostly text work with little code could use a plain text editor for Quarto documents; rendered HTML documents can be previewed in a browser.
Allaire believes that one of the biggest Quarto advantages is assistance in writing YAML, the language used for both R Markdown and Quarto document header information. YAML can be annoyingly finicky as to where to place colons, commas, and indentations. It’s almost like its own programming language, but without the advantages of an IDE and error-checking. The Quarto editor has built-in YAML assistance. It also aims to highlight errors before you try rendering your document and finding out that it won’t work.
And since Quarto is open source, others can contribute to its functionality by writing extensions. There are several Quarto extensions already available from the Quarto development team.
Another potential advantage, depending on your needs: You can export Quarto documents in more than 40 different file formats including Word, OpenOffice, PowerPoint, ePub, Jira Wiki, Jupyter, Observable JS, complete websites, and ebooks. R Markdown can generate some of those, but not all.
There are also some useful conversion functions, such as converting between .ipynb Jupyter notebooks and .qmd Quarto documents that can be read by any text editor.
Finally, while R Markdown will be maintained and updated, “[RStudio] will probably not try to backport Quarto features into R Markdown (unless it is fairly straightforward and takes little effort),” RStudio engineer Yihui Xie wrote in a blog post. In other words, cool new features are much more likely to appear in Quarto.
However, Quarto does not mean the end of R Markdown. “Rest assured #rmarkdown is not going away: We’ll continue to work it! No need to switch #rstats if you don’t need to,” tweeted Christophe Dervieux, a software engineer at RStudio. In fact, most things you know from R Markdown probably can be used in Quarto. And, Quarto will render R Markdown documents.
How is Quarto different from R Markdown?
Unlike R Markdown, which is an R package, Quarto is a separate, non-R application. So in order to use Quarto, you may first need to download and install it like you would any other software, in this case from the quarto.org “Get Started” page. Quarto is currently included in RStudio IDE versions RStudio v2022.07.1 or later.
For Visual Studio Code, install both Quarto and the VS Code Quarto extension. Quarto also works with Jupyter Lab and any text editor
If you’ve used R Markdown before, a Quarto document will look familiar. There’s a YAML header with a title, author, and output format. Text uses a lot of generic markdown, such as pound signs for headers and bracket/parentheses syntax for hyperlinked text: [linked text](https://theurl.com). Both use three backticks to delineate the start and end of code chunks.
Screenshot by Sharon Machlis
Sample Quarto document in RStudio.
One of the biggest differences between older R Markdown and Quarto is how you set up options for code chunks. In R Markdown, chunk-specific options were typically put within curly braces defining the chunk, such as
```{r chunk_name, echo=FALSE, warning=FALSE}
code here
```This creates a block of R code named chunk_name that will be executed, but the code itself won’t display in the rendered document. And any warning messages the code might generate will not appear.
In Quarto, chunk options go below the curly braces. Each option goes on its own line preceded by a pound sign and vertical character, such as
```
{r}
#| label: chunk_name
#| echo: false
#| warning: false
```
This "hash pipe" chunk-option format now also works with R Markdown documents.
For more details on using Quarto, see the Quarto website or slides by Mine Çetinkaya-Rundel, a professor at Duke University who also does work at RStudio, from her RStudio Conference keynote with Stewart Lowndes.
In addition, Quarto has its ow Twitter account. And there’s the Quarto Tip a Day blog by Mine Çetinkaya-Rundel.
If you'd like to try publishing a public Quarto HTML document, RStudio launched a free site https://quartopub.com similar to its older RPubs for R Markdown docs.
To learn more about the R programming language, head to the Do More With R tutorials page.