When I started planning this blog, I intended to create it using R Markdown with Blogdown. But right before I committed, I learned about Quarto, a new Markdown variant with intriguing features. I decided to go with Quarto, and it proved the right decision. This post is about how Quarto extends R Markdown’s already formidable capabilities to produce all kinds of documents.
R Markdown
R Markdown is a file type based on Markdown. It is designed for writing documents that combine “chunks” of R code with plain text. An R Markdown document can be “rendered” into several different types of output, most commonly .html or .pdf. Rendering executes R code contained in chunks and displays the outputs in the resulting document alongside text.
R Markdown is well suited for typical data science work products. When writing a report or article, it’s easy to combine code with prose that explains what it does. First, you write a code chunk in your document like this:
This important plot shows that two
principal components capture almost
all of the variance within mtcars
```{r}
plot(princomp(mtcars))
```
When the document is rendered, the code is executed and displayed above the results.
The format also renders LaTeX, which means you can write all kinds of math formulae, like this set identity:
\[ |A \cup B| = |A| + |B| - |A \cap B| \]
I learned R Markdown format before my first semester of grad school, and I used it from the start to make reports to my assistantship supervisor. I became more familiar with it after changing to a data science degree. Since the data science department at my school mostly used R, it was the required format for most assignments. Its LaTeX capabilities also came in handy for linear algebra homework.
But a few pain points emerged over time. There was no built-in shell command to render a document from the terminal; you had to run the render command in R by executing R -e 'rmarkdown::render("thefile.Rmd")' or similar. Many people used R Markdown to write blogs, but no built-in support existed, forcing them to rely on external packages like Blogdown. Most obviously, it was fundamentally _R_ markdown. While the format can render an impressive number of non-R languages, like SQL or Bash, it was designed and intended for R, not other ecosystems. If you want to render an R Markdown file as a Jupyter notebook, a ubiquitous format in data science, you’ll need to use a third-party tool.
Drawn and Quartoed
Quarto does all these things and more. It features a command-line interface that can render files, preview outputs, create projects, and more. It supports Jupyter notebook outputs and offers a cleaner interface for setting chunk options than R Markdown. Most importantly for my use case, Quarto was designed to support blog editing natively. The docs even have a step-by-step guide.
All that aside, Quarto also supports the usual R Markdown features. You can run code from various languages, customize chunks to your heart’s content, and use LaTeX freely.
These facts make Quarto ideal for a blog like this. The workflow is simple. When I want to write a new post, I change directory to the project root and create posts/important-content/index.qmd, where important-content is the post title. (But I repeat myself, for all my content is important). Then I write index.qmd, the file that will be turned into an HTML document containing the post text. Once done, I use quarto render posts/important-content to create the HTML output, then quarto preview to find out how it would look once uploaded. I make any needed tweaks, then repeat the process. Once satisfied, I git commit and push to the repository where the blog lives.
I’m sure I’ll discover some pain points with Quarto eventually, but so far it’s been a smooth experience. And when I do, I’m pretty confident they’ll be resolved with the successor file format.