Section 2 YAML header

YAML header is a short blob of text, specially formatted with key: value pairs tags, that seats at the top of our Rmarkdown document. The header not only dictates the final file format, but a style and feel for our final document. Later in the book we will learn that YAML header can seat in a stand alone file, such as _site.yml or __output.yml.

2.1 Introduction

Let’s begging by adding some personality to our document via YAML configuration. For now we are going to be embedding YAML header into our document right at the top. The header needs to be enclosed in triple dashes on either side as following

---
# header here
---

Inside YAML header we can use # symbol to indicate a comment, those won’t have any effect on the document

Typical structure of the YAML header is key, value pairs separated by a colon e.g

---
key: value
---

YAML is hierarchical and can have nested structure, key value pairs e.g

---
key1:
  value1:
    key1.1: value1.1
    key1.2: value1.2
---

Spaces (indentation) is very important to YAML header, so be sure to indent correct amount. Below are two examples of the valid YAML headers and one example of the invalid YAML header

2.1.1 Example 1 (Correct YAML)

This is a valid yaml header. In this example we have a key title with scalar value Learning Rmarkdown

---
title: "Learning Rmarkdown"
---

2.1.2 Example 2 (Correct YAML)

This is also valid YAML header. Here we have rmd_files key with list of values. We can specify a list value in two way

---
rmd_files: ["00-index.Rmd", "01-introduction.Rmd"]
---

Alternatively

---
rmd_files:
  - 00-index.Rmd
  - 01-introduction.Rmd
---

2.1.3 Example 3 (Incorrect YAML)

This on the other hand is incorrect YAML header because we are not specify a list values correctly

---
rmd_files:
  00-index.Rmd
  01-introduction.Rmd
---

— Alright, Let’s try it out!

2.2 Title, date and author keys

Let’s add our first YAML header to the top of our document. Let’s include the title of the document, author name i.e yourself and date. Note a nice trick of including inline R code inside the YAML header.

Press Knit button to render the document

---
title: "Rmarkdown"
author: "Kirill"
date: "2020-11-16"
---

2.3 Output key

Output is one of the central keys in Rmarkdown ecosystem, arguably. The final results directly depends on the value you are going to use for that key.

Rmarkdown package can output several document types, each has various ke, value pairs a.k.a options of flags, refere to the documentation page for more information prefixing function name a ?. Here are most common document types:

rmarkdown::html_document
rmarkdown::ioslides_presentation
rmarkdown::word_document

Let’s try out html_document output type by including it into our YAML header and press Knit

output: html_document

If you don’t see much difference after including html_document this is because it is the default output. Now, however, we have means to further configurate our html document.

2.4 Configuring output document

We will learn a bit later how to get information about all possible key, value pairs for any given document type, for now let’s just explores these few. Let’s add toc and theme keys to our YAML header and press Knit

output:
  html_document:
    toc: true
    theme: readable

— This looks great!

2.5 Final look

Just in case you’ve got lost, this is how our first section should look like

---
title: "Rmarkdown"
author: "Kirill"
date: "2020-11-16"
output:
  html_document:
    toc: true
    theme: readable
---