The YAML Problem

---

---
class: middle

---

---

## *Even the creator of R Markdown and knitr isn't crazy about YAML*

---
class: inverse, middle, center

# *YAML:*

# **Yet Another Markup Language**

# **YAML Ain't Markup Language**

---

---

---

---

---

---

```text
library(ymlthis)
as_yml(
"title: Annual Report
author: Malcolm Barrett
date: '`r Sys.Date()`'
output:
  pdf_document:
    toc: true
"
) %>% draw_yml_tree()
```

---

```text
library(ymlthis)
as_yml(
"title: Annual Report
author: Malcolm Barrett
date: '`r Sys.Date()`'
output:
  pdf_document:
    toc: true
"
*) %>% draw_yml_tree()
```

---

```text
library(ymlthis)
as_yml(
"title: Annual Report
author: Malcolm Barrett
date: '`r Sys.Date()`'
output:
  pdf_document:
    toc: true
"
) %>% draw_yml_tree()
```

```
├── title: Annual Report
├── author: Malcolm Barrett
├── date: '`r Sys.Date()`'
*└── output:
*    └── pdf_document:
*        └── toc: true
```

---

## ⚠️ **YAML fails silently**

---

# Introducing ymlthis

---

# Introducing ymlthis

## ✔️ **Write YAML**
---

# Introducing ymlthis

## ~~✔️ Write YAML~~
## ✔️ **Document YAML**

---

# Introducing ymlthis

## ~~✔️ Write YAML~~
## ~~✔️ Document YAML~~
## ✔️ **Improve R Markdown Workflows**

---

# Introducing ymlthis

## ~~✔️ Write YAML~~
## ~~✔️ Document YAML~~
## ~~✔️ Improve R Markdown Workflows~~
## 📥 **Validation**

---

# Writing YAML

```text
yml()
```

---

# Writing YAML

```text
yml()
```

```
---
author: Malcolm Barrett
date: '`r format(Sys.Date())`'
---
```

---

# Writing YAML

```text
yml() %>% 
* yml_output(
*   pdf_document(toc = TRUE),
    html_document()
  )
```
---

# Writing YAML

```text
yml() %>% 
* yml_output(
*   pdf_document(toc = TRUE),
    html_document()
  )
```

```
---
author: Malcolm Barrett
date: '`r format(Sys.Date())`'
*output:
*  pdf_document:
*    toc: true
  html_document: default
---
```

---

# Writing YAML

```text
yml() %>%
* yml_author(
*   c("Yihui Xie", "Hadley Wickham"),
*   affiliation = "RStudio"
  ) %>%
  yml_date("07/04/2019") %>%
  yml_title("Reproducible Research in R") %>% 
* yml_category(c("r", "reprodicibility")) %>%
  yml_output(
    pdf_document(
      keep_tex = TRUE,
      includes = includes2(after_body = "footer.tex")
    )
  ) %>%
* yml_latex_opts(biblio_style = "apalike")
```

---

# Writing YAML

```
---
author:
*- name: Yihui Xie
*  affiliation: RStudio
*- name: Hadley Wickham
*  affiliation: RStudio
date: 07/04/2019
title: Reproducible Research in R
*category:
*- r
*- reprodicibility
output:
  pdf_document:
    keep_tex: true
    includes:
      after_body: footer.tex
*biblio-style: apalike
---
```

---

# R Markdown Extensions

.large[
| package| output function | top-level YAML |
|--:|--:|--:|
| bookdown | ✓ | ✓ |
| blogdown | ✓ | ✓ |
| pkgdown | ✓ | ✓ |
| pagedown | ✓ | ✓ |
| rticles | ✓ | ✓ |
| distill | ✓ | ✓ |
| learnr | ✓ | ✗|
| xaringan | ✓ | ✗|
| revealjs | ✓ | ✗|
| flexdashboard | ✓ | ✗|
]

---

# Documenting YAML

## ?`yml_*()`

---

---

# Improving R Markdown Workflows
## `use_yml()`

```text
yml() %>%
  use_yml()
```

```
  ---
  author: Malcolm Barrett
  date: '`r format(Sys.Date())`'
  ---
● Paste into R Markdown or YAML file
```

```text
# Places YAML on your cliboard
```

---

# Improving R Markdown Workflows
## `use_rmarkdown()`

```text
yml() %>%
  use_rmarkdown()
# opens a new R Markdown file
```

---

# Improving R Markdown Workflows

```text
bookdown_yaml <- yml() %>% yml_output(bookdown::pdf_document2())
*use_yml_defaults(bookdown_yaml)
```

---

# Improving R Markdown Workflows

```text
bookdown_yaml <- yml() %>% yml_output(bookdown::pdf_document2())
use_yml_defaults(bookdown_yaml)
```

```
*  options(ymlthis.default_yml = "author: Malcolm Barrett
*  date: '`r format(Sys.Date())`'
*  output: bookdown::pdf_document2")
● Run interactively or paste into .Rprofile (perhaps using `usethis::edit_r_profile()`)
```

---

# Improving R Markdown Workflows

```text
bookdown_yaml <- yml() %>% yml_output(bookdown::pdf_document2())
use_yml_defaults(bookdown_yaml) 
```

```
  options(ymlthis.default_yml = "author: Malcolm Barrett
  date: '`r format(Sys.Date())`'
  output: bookdown::pdf_document2")
● Run interactively or paste into .Rprofile (perhaps using `usethis::edit_r_profile()`)
```

```text
*use_rmarkdown()
```

---

### Write to `.Rmd` files

### Write to `.yml` files

---

# visit the site for tutorials and documentation
# [**http://ymlthis.r-lib.org**](http://ymlthis.r-lib.org)

---

![](https://media.giphy.com/media/3oz8xIsloV7zOmt81G/giphy.gif)

### [malcolmbarrett](https://github.com/malcolmbarrett/)
### [@malco_barrett](https://twitter.com/malco_barrett)

Slides created via the R package [xaringan](https://github.com/yihui/xaringan).