Quarto Background

Tip Learning Objectives

By the end of this module, you will be able to:

  • Explain why Quarto is useful in this context
  • Define the three critical parts of a Quarto file
  • Describe why some Quarto projects use a single YAML file across multiple Quarto documents

Why Quarto

Quarto is new software developed by Posit–the company that maintains Positron and RStudio. Quarto is extremely versatile and supports several programming languages. Quarto documents are structurally similar to RMarkdown files (more on this later) but are more efficient and easily support a variety of ‘bells and whistles’ that make it worthwhile to embrace.

This workshop uses Quarto for the following reasons:

  • The learning curve for novice coders is relatively gentle
    • Much R knowledge and intuition is directly transferable!
  • Making a (simple) website is straightforward
  • Quarto can be used in a variety of applications
    • So learning it here will give you tools you can apply elsewhere!

If you’re broadly curious about Quarto, check out their website, quarto.org.

Key Quarto File Components

Quarto documents are a type of “computational notebook” like RMarkdown files and–for python coders–Jupyter Notebooks. These notebook files can include runnable-code as well as plain text description of that code. Often, notebooks are used to simultaneously run a given code workflow while embedding the documentation for that workflow in the same file; this can be a great choice for reproducibility!

Notebook files contain three fundamental components that allow them to be “rendered” (sometimes also called “knit”) to produce a new static report file. This is often a PDF or an HTML file though for website purposes we’ll be using the HTML version so that each notebook file can become a page in your website.

Typically, these notebooks have three structural components:

  1. YAML
    • Pronounced [ YEAH-mull ]
  2. Embedded code chunks
  3. Plain text
    • Possibly formatted with Markdown syntax

The YAML (Yet Another Markup Language) defines document-level metadata. Most fundamentally, the YAML defines what file type will be produced when the report is rendered. It can also be used to define the top-level title, author, and date information. Finally, it can change the default options for code chunks throughout the document (more on code chunk options elsewhere).

Different notebook file types will specify the YAML differently but in both Quarto documents and R Markdown files, the YAML is defined in the first few lines of the report and starts/ends with a line containing three hyphens. This looks something like this:

---
title: "Reproducible Reports"
output: html_document
---

Among other roles, the YAML defines what type of output file is produced when the notebook is “rendered” (a.k.a. “knit”). Most commonly this is either a single PDF or HTML file but more complex YAMLs can be used to create full websites or scientific manuscripts!

The text outside of the YAML and code chunks is plain text that accepts Markdown syntax to accomplish text format tweaks. Dedicated text-formatting software (e.g., Microsoft Word, Gmail, etc.) provides buttons and hot keys for these sorts of format alterations but many programming IDEs do not provide such user interface elements.[^1] Markdown syntax is used to support this same functionality.

Some fundamental Markdown options include:

  • **bold text** bold text
  • _italic text_ italic text
  • `code text` code text
  • [hyperlinked text](https://lter.github.io/ssecr/mod_reports.html) hyperlinked text

For a more complete glossary of fundamental Markdown syntax options see here. You may also want to explore the ‘back end’ of this workshop’s website as every page is built using Quarto documents.

The code chunks embedded in notebooks are essentially a fragmented script containing runnable code. These chunks may contain code and/or comments and share an environment with one another when rendered (i.e., if you load a particular library in one chunk you’ll be able to use functions from that library in subsequent chunks). When used in concert with the Markdown text in a given notebook the code chunks can be used to effectively demonstrate a workflow while providing as much human-readable context as is desired.

In Quarto documents, code chunks look like this[^2]:

```{r}
#| label: demo-chunk
#| echo: true

# Round pi to 2 digits
round(x = pi, digits = 2)
```
1
You may specify chunk-specific options using this syntax (i.e., #| option_name: option_setting). Options you want to apply to all chunks across a notebook should be specified once in the YAML and can exclude the leading #| bit of the format.
2
If your Markdown text provides sufficient context you may exclude comments in code chunks but opinions differ on which is “more” appropriate

File-Specific vs. Global YAMLs

When working in a single Quarto document, that document needs its own YAML so that Quarto ‘knows’ how to render it. However, for multi-document projects like websites a global YAML is required. This is because defining project-wide behavior across each file’s specific YAML would be intensely cumbersome.

This global YAML file controls project-wide (i.e., across-document) formatting and structure. You can still use the YAML section within a single document if you want it to behave differently from other pages but any formatting you want to apply across all Quarto files in the project should be specified in this cross-document, global YAML.

We’ll discuss what goes into that project-wide YAML later in the workshop but for now it is only important you understand its general purpose and know that it must always be named _quarto.yml for it to work as you expect.