Quarto documents

Quarto documents provide a way to mix together Markdown text with code and its results. Whereas R scripts are designed primarily for writing and running code—with comments (#) giving a means to document the code—Quarto documents allow you to write prose alongside code. You can then output the Quarto document into a number of formats, including web pages, PDFs, slides, and even Word documents. Projects of connected Quarto documents can create books and full websites. Why might you use Quarto documents instead of an R script?

1. To communicate a data analysis with calculations and visualizations, but you do not need the code that produced the analysis to be shown in the final document.
2. If you want to write extensive text or write structured text with Markdown between your blocks of code.
3. If you want to create a stylized output such as web pages, PDFs, slides, and more from Markdown whether it includes code or not.

To get familiar with Quarto, please download this Quarto template document, place it in your r-notes project, read through it, and then render it into an HTML document.

Resources

The rest of this page goes over the foundations of Quarto documents, but there are a couple of very good resources that should be consulted to get a fuller understanding of how and why to use Quarto documents.

• A good place to start is with the Getting started with Quarto tutorial for RStudio. It provides an overview of how to write and render Quarto documents into a variety of formats in RStudio. Make sure to go through all three pages of Hello, Quarto, Computations, and Authoring.
• Once you have gone through the tutorial, look over the Quarto chapter of R for Data Science.
• The Quarto documentation is very good and very in depth. It is a good place to return to each time you have a question. Some particularly useful pages include:
  • Markdown basics
  • Using R
  • Quarto in RStudio
  • HTML basics

Quarto foundations

A Quarto document is a plain text file that has a .qmd extension. It contains three basic components:

1. A YAML header contained within lines with three dashes (---).
2. Markdown text.
3. Code chunks set off by three back ticks (```).

Figure 1: A Quarto document in RStudio.

The key distinguishing feature between Quarto documents and R scripts is that you can render Quarto documents to different outputs. Rendering a Quarto document with the Render button or Cmd/Ctrl + Shift + K runs the R (or Python) code, producing outputs and converting the document to a Markdown document. It then uses Pandoc to convert the Markdown document to whatever output is specified in the YAML heading. The process is shown in Figure 2.

Figure 2: Diagram of the process of rendering a Quarto document. Image is from Wickham et al., R for Data Science, Quarto.

Quarto in RStudio

The Get Started page of the Quarto documentation shows that you can write Quarto documents in a variety of applications. However, RStudio has many built-in functions that make it easier to work with Quarto documents. You can make a new Quarto document by going to File -> New Document -> Quarto Document… You can add information to the dialogue to fill in the YAML heading, or you can choose Create Empty Document.

Figure 3: Dialogue box to create a new Quarto document.

Quarto documents can be edited in either the Visual editor or the Source editor. The Visual editor styles your text as you go, whereas the source editor will give you an interface that is more similar to R scripts. You can change back and forth with the buttons at the top of the editor pane, but do note that this can slightly change how your Markdown is written.

Quarto’s three components

1. YAML header

The YAML header provides a way to indicate the title of the document, document metadata such as author, the output format(s), and document wide options. YAML is a way to store data in a human-readable form. Its basic structure is key: value. The YAML heading is set off by three dashes ---. A somewhat complex heading might look like this:

---
title: "My title here"
author:
  - name: "Jesse Sadler"
    email: jrsadler@vt.edu
    affiliation: "University Libraries"
date: last-modified
format:
  html:
    toc: true
    abstract: |
      This is the abstract.

      It has two paragraphs.
execute:
  echo: false
  warning: false
---

The available keys can be found in the documentation for each type of output.¹ Many options are shared across document output types, but some are not. See the HTML options for the widest number of options. It can be difficult to write these YAML headers. There are a lot of different options, and the indentation level must be formatted correctly. Happily, in practice, it is unlikely to be as difficult it looks. Firstly, you will not need to write complex YAML headers often. Secondly, you can figure out settings that work for you and then copy and paste them into other documents. There are also ways for YAML options to be used for all documents in a project such as a website.

2. Markdown

Unlike R scripts where default text is code, the default text in Quarto documents is Markdown. Use Resources: Markdown syntax for Markdown foundations, and look at the Quarto Markdown documentation for more details on the style of Markdown you can use in Quarto documents.

3. Code chunks

With Markdown as the default editing environment, your code must be placed in code chunks set off by three back ticks (```). They look like this:

```{r}
24 + 87
```

[1] 111

You can create code chunks in RStudio with:

1. The keyboard shortcut: Cmd + Option + I or Ctrl + Alt + I.
2. Typing the chunk delimiters ```{r} and ```.

Once inside a code chunk, text functions as it does in an R script. Comments are made with #. Everything else is code. You can run the expressions in a chunk with Cmd + Return or Ctrl + Enter. Or you can run the entire chunk with the play button at the top right of the chunk. The output of the chunks will either be placed directly below the chunk or sent to the console. You can alter this in Global Options -> R Markdown tab -> Show output inline for all R Markdown documents checkbox. See also Other tweaks section in Setting up RStudio for success.

The primary difference between code chunks and R scripts is that code chunks can have special comments created with #| that provide options for the output of the chunk. These are formatted as YAML and override any defaults set in the YAML header. You can see the full list of options in the Quarto documentation.

```{r}
#| label: some-math
#| eval: false
24 + 87
```

The label option names the chunk, making it easier to refer to the chunk and to see it in the outline in RStudio. label names should be short and not include spaces. It is recommended to use a dash between words.

The main options that affect the execution of code are:

• eval: false prevents the code from being run. The code displays but does not run.
• echo: false prevents the code from being shown in the output, but the code is run and outputs are shown. This is useful when you want people to see the output but the code does not need to be read by the audience.
• include: false prevents the code and outputs from being shown, though the code is run. This is useful for setup code.
• message: false or warning: false prevents messages or warnings from being output in the rendered document.

The other options you might want to change are the figure output. See R for Data Science for more details.

• To set the size of the plot from ggplot2:
  • fig-width: 6
  • fig-asp: 0.618: Aspect ration of width to height. With this you do not need to set the width. 0.618 is the golden ratio.
  • fig-width: 4: But you can set width instead of aspect.
• Control the output size within the output document:
  • out-width: "70%": This would take up 70% of the content area.
  • fig-align: center: How to align the plots.

Output formats

You can create a number of different types of documents from Quarto documents. The default is HTML documents ready to be put on the web or viewed through your browser, but you can also make PDFs, presentations, dashboards, and even Word documents. It is also possible to combine multiple Quarto documents together into projects such as websites and books.

You control the output of individual documents either in the document YAML or in rendering the document via the command line. Generally, you will want to use the document YAM using the format key.

• HTML: format: html
• PDF: format: pdf or format: typst
• Presentation: format: revealjs
• Word: format: docx

Most options within the YAML are shared across output formats, but not all formats have all the capabilities. Look at the reference documentation for each type to see the available options.

A note on PDF formats

If you want to output a PDF, you have two different choices, format: pdf uses Pandoc to create the PDF; format: typst uses Typst. The Pandoc format has more options, but Typst is a more modern PDF engine and has nicer looking defaults.

Project outputs

Projects contain multiple Quarto documents and use a _quarto.yml file to share the YAML metadata options across all of the documents within the project. If you want different YAML options in one or more documents within the project, you can modify the YAML in the document itself. The options written in the document will take precedence over those written in the _quarto.yml file. This means that generally the YAML heading for individual documents in a project might only have a title. See Quarto websites for more on working with Quarto projects.

Conclusion

This is just the tip of the iceberg for what you can do with Quarto documents. But you can do a lot with these foundations. Check out the Resources above for places to start if this document does not cover a question you have.

Footnotes

1. See the Output formats section for more details on output formats.