Introducing ymlthis: a toolkit for working with YAML

I’m pleased to announce that ymlthis 0.1.0, my project for my summer internship at RStudio, is now on CRAN! ymlthis is a toolkit to reduce the pain of working with YAML in the context of R Markdown documents. The two most common issues when working with YAML are getting the syntax right, particularly the white space, and understanding what options you can specify. ymlthis solves these problems by building and documenting YAML from R. ymlthis supports many other R Markdown packages, such as blogdown, bookdown, and pkgdown, and also offers new ways of working with R Markdown and YAML files.

# install from CRAN
install.packages("ymlthis")

Write YAML

yml() is the basic building-block of ymlthis; by default, it adds your name and R code to write today’s date programmatically.

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

ymlthis uses the pipe syntax to add more elements to the underlying YAML.

yml() %>% 
  yml_output(bookdown::html_document2(toc = TRUE)) %>% 
  yml_title("Introducing ymlthis") %>% 
  yml_category(c("r", "rmarkdown", "yaml")) %>% 
  yml_citations(
    bibliography = "references.bib", # file with citations
    csl = "aje.csl" # file with citation styles
  )
---
author: Malcolm Barrett
date: '`r format(Sys.Date())`'
output:
  bookdown::html_document2:
    toc: true
title: Introducing ymlthis
category:
- r
- rmarkdown
- yaml
bibliography: references.bib
csl: aje.csl
---

These functions all start with yml_*(). YAML functions and helper functions for R Markdown extensions start with yml_packagename*() or packagename_*(). For instance, blogdown functions follow the pattern yml_blogdown*() and blogdown_*().

Write R Markdown and YAML files

ymlthis prints cleanly to the console, so you can easily copy and paste it into your R Markdown document (or use use_yml() to programatically place it on your clipboard). If you want a more complete workflow, use_rmarkdown() and friends take yml objects and write them to R Markdown and YAML files.

use_rmarkdown(path = "myreport.Rmd")
## ✔ Writing '/var/folders/03/9x7925g54mncswxx06wpkxl00000gn/T/RtmpjII0sB/file1d557810ebcc/myreport.Rmd'

Read the vignette introducing ymlthis for more on working with R Markdown and YAML files, as well as for using ymlthis to create R Markdown templates.

Learn more about YAML and YAML options

Because these YAML fields are expressed as R function arguments, they are explicitly documented in yml_*() functions. For instance, if you want to know the LaTeX options you can set while knitting to a PDF file, you can look at the help page for ?yml_latex_opts(). If you’re not quite sure where to look, all of the YAML fields documented in ymlthis are compiled in a single place in the YAML Fieldguide.

ymlthis also has a vignette introducing YAML in general, if you’d like to learn more about using it directly.

Where do I learn more about ymlthis?

Learn more about ymlthis on the package website. There you’ll find articles on with a detailed introduction to ymlthis, introducing YAML, and the YAML Fieldguide, which documents in one place all the YAML fields contained in ymlthis.

Please feel free to post any issues to the GitHub repository!

Avatar
Malcolm Barrett
PhD Student in Epidemiology

I am an R developer and a PhD student in Epidemiology at the University of Southern California. My work in public health has spanned on-ground clinical education and research for clinical and cohort studies. Previously, I was an intern at RStudio, and I served two years in AmeriCorps at federally-qualified health centers in Michigan and New York City.

Related