YAML: an Overview

Basic syntax

The basic syntax of YAML is to use key-value pairs in the format key: value. A YAML code block should be fenced in with --- before and after (you can also use ... to end the YAML block, but this is not very common in R Markdown).

---
author: Malcolm Barrett
---

In R, the equivalent structure is a list with named character vector: list(author = "Malcolm Barrett"). In fact, you can call this list in R Markdown using the metadata object; in this case, metadata$author will return "Malcolm Barrett"

In YAML, spaces are used to indicate nesting. When we want to specify the output function pdf_document(toc = TRUE), we need to nest it under the output field. We also need to nest toc under pdf_document so that it gets passed to that function correctly.

---
output:
  pdf_document:
    toc: true
---

In R, the equivalent structure is a nested list, each with a name: list(output = list(pdf_document = list(toc = TRUE))). Similarly, you can call this in R Markdown using the metadata object, e.g. metadata$output$pdf_document$toc. The hierarchical structure (which you can see with draw_yml_tree()) looks like this:

└── output:
    └── pdf_document:
        └── toc: true

Without the extra indents, YAML doesn’t know toc is connected to pdf_document and thinks the value of pdf_document is NULL. YAML that looks like this:

---
output:
  pdf_document:
toc: true
---

has a hierarchy that looks like this:

├── output:
│   └── pdf_document: null
└── toc: true

If you use output functions without additional arguments, the value of output can simply be the name of the function.

---
output: html_document
---

However, if you’re specifying more than one output type, you must use the nesting syntax. If you don’t want to include additional arguments, use "default" as the function’s value.

---
output:
  html_document: default
  pdf_document:
    toc: true
---

Some YAML fields take unnamed vectors as their value. You can specify an element of the vector by adding a new line and - (note that the values are not indented below category here).

---
category:
- R
- Reprodicible Research
---

In R, the equivalent structure is a list with a named vector: list(categories = c("R", "Reprodicible Research")). metadata$category will return c("R", "Reprodicible Research"). Another way to specify vectors is to use [] with each object separated by a column, as in the syntax for c(). This YAML is equivalent to the YAML above:

---
category: [R, Reprodicible Research]
---

By default, ymlthis uses the - syntax for vectors.- is also used to group elements together. For instance, in the params field for parameterized reports, we group parameter information together by using -. The first line is the name and value of the parameter, while all the lines until the next - are extra information about the parameter. While you can use metadata to call objects in params, params has it’s own object you can call directly: params$a and params$data will return the values of a and data.

---
params:
- a: 1.0
  input: numeric
- data: data.csv
  input: text
---

In R, the equivalent structure is a nested list that contains a list of unnamed lists: list(param = list(list(a = 1, input = numeric), list(data = "data.csv", input = "file"))). The inner-most lists group items together, e.g. list(a = 1, input = numeric) groups a and input.

└── params:
    ├── a: 1.0
    └── input: numeric
    ├── data: data.csv
    └── input: text

Types in YAML

You may have noticed that strings in YAML don’t always need to be quoted. However, it can be useful to explicitly wrap strings in quotes when they contain special characters like : and @.

---
title: 'R Markdown: An Introduction'
---

R code can be written as inline expressions `r expr`. yml_code() will capture R code for you and put it in a valid format. R code in params needs to be slightly different: use !r (e.g. !r expr) to call an R object.

author: '`r whoami::fullname()`'
params:
  date: !r Sys.Date()

Logical values in YAML are unusual: true/false, yes/no, and on/off are all equivalent to TRUE/FALSE in R. Any of these turn on the table of contents:

toc: true
toc: yes
toc: on

By default, ymlthis uses true/false. If you want to use any of these values literally (e.g. you want a string equal to "yes"), you need to wrap them in quotation marks:

---
params:
  x: 'yes'
---

NULL can be specified using null or ~. By default, ymlthis uses null. If you want to specify an empty vector, use [], e.g. category: []. For an empty string, just use empty quotation marks ("").

Sources of YAML

Where do the YAML fields you use in R Markdown come from? Many YAML fields that we use come from Pandoc from the rmarkdown package. These both use YAML to specify the build of the document and to pass information to be printed in a template. Pandoc templates can also be customized to add new YAML. The most common sources of YAML are:

  1. Pandoc
  2. R Markdown
  3. Output functions (such as rmarkdown::pdf_document())
  4. Custom Pandoc templates
  5. R Markdown extension packages (such as blogdown)
  6. Hugo (in the case of blogdown)

Because YAML is an extensible approach to metadata, and there is often no way to validate that your YAML is correct. YAML will often fail silently if you, for instance, make a typo in the field name or misspecify the nesting between fields. For more information on the fields available in R Markdown and friends, see the YAML Fieldguide.