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")
yml() is the basic building-block of ymlthis; by default, it adds your name and R code to write today’s date programmatically.
--- 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
packagename_*(). For instance, blogdown functions follow the pattern
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!