YAML

Author
Affiliation

David Schoch

GESIS

Published

2023-06-19

Quarto is a very versatile tool that can create documents in many different formats. Switching between formats does not mean that you need to switch programs. The only thing that needs to be changed is the documents “configuration”. Quarto documents are configured via a YAML header.

What is YAML?

  • YAML stands for “YAML Ain’t Markup Language” (It rhymes with “camel”)

  • YAML is a very simple, text-based, human-readable language used to exchange data between people and computers.

  • YAML is not a programming language but used for storing configuration information.

  • YAML stores data. It does not include commands and instructions.

  • YAML is similar to XML or JSON but much more human readable and concise.

Basic Configuration of Quarto via YAML

Single Document

A single .qmd document always starts with a YAML header. The minimum working header just includes the format of the document.1

---
format: html
---

To specify options for the output format use the scheme.

---
format: 
  html:
    toc: true
    code-fold: true
---

YAML is very sensitive to malformed instructions. Create a default quarto document in RStudio (File > New File > Quarto Document…) and add a (random) title. Replace the YAML header with each of the following:

---
format:html
---
---
format: 
html
---
---
format: 
  html:
    toc: true
---

Observe the outcome when rendering and try to identify the source of error if there is one.

Project

A Quarto projects is simply a set of documents put together into a single resource (like a book or a website). In this case, the YAML configuration happens in a configuration file called _quarto.yml. We’ll explore this in more detail in the session about websites, but in essence, most of what is discussed here for a single document also holds for _quarto.yml.

Exploring additional YAML options

To see all available options for the YAML header, either consult the reference or in RStudio, while having the cursor within the YAML header, press CTRL + space

Start from a default qmd file and add a title, subtitle, author information and anything else you find interesting while exploring the option. Render the result to different output formats and observe the differences between documents.

Note that not all options apply to all output formats. Try to set a theme for your HTML document and then render it as a PDF. What do you observe?

Project

Try to export your CV to PDF and/or MS Word and apply some YAML options you find useful (html themes in particular).

Footnotes

  1. If you create a new document via RStudio (File > New File > Quarto Document…) then you are also required to add a title.↩︎