An Introduction to ymlthis

ymlthis is a package to help you write YAML metadata for R Markdown documents and related tools like blogdown, bookdown, and pkgdown. YAML serves two main roles: to pass information to be printed in the document, such as the title and author, and to control how the document is rendered, anything from the output type (HTML vs. PDF) and typesetting options to what should happen with files created while rendering. See the YAML: An Overview for a more general introduction to YAML and the YAML Fieldguide for YAML field documentation.

# Writing YAML with ymlthis

ymlthis makes it easy to write valid YAML by handling the syntax and documenting the majority of YAML fields in one place. `yml()` creates a `yml` object that, by default, sets the author name and date. ymlthis uses name options in devtools and usethis (`options(devtools.name = "name")` and `options(usethis.full_name = "name")`, respectively), as well as the whoami package, to try to find the author’s name. By default, the date is set to ``r format(Sys.Date())``, which will update the date when knitting.

    yml()

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

Functions that start with `yml_*()` take and return `yml` objects, so they can be used to add or modify YAML fields. For instance, to add a title, use `yml_title()`

    yml() %>%
      yml_title("An introduction to ymlthis")

    ---
    author: Malcolm Barrett
    date: '`r format(Sys.Date())`'
    title: An introduction to ymlthis
    ---

An essential use of YAML in R Markdown is to set the output type. By default, the `output` YAML field looks like

    output: html_document

which calls `rmarkdown::html_document()` when knitting. All of the nested fields passed to `output` come from the output function you are using (so you can check `?pkg::output_function()` to see what the options are). ymlthis writes and validates output YAML by parsing calls to these functions. We can, for example, nest R Markdown’s `pdf_document()` inside `yml_output()`:

    yml() %>%
      yml_output(pdf_document())

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

Passing arguments to the output functions will nest them correctly for YAML.

    yml() %>%
      yml_output(pdf_document(toc = TRUE))

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

And we can pass multiple output functions to facilitate rendering R Markdown files to multiple formats:

    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
    ---

YAML fields can come from a variety of places: R Markdown itself, the output function, Pandoc (for example, as options used in LaTeX), and custom templates. Many of these fields are documented in `yml_*()` functions.

    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")

    ---
    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
    ---

You can also use `yml_toplevel()` to append any YAML fields not covered in ymlthis.

## Parameterized reports

Parameterized reports are a powerful feature of R Markdown that lets you specify variables in the YAML metadata used in your report, letting you re-use reports for a variety of settings. To set parameters, you use the `params` YAML field and access the parameter in your report by calling `params$variable_name`. Basic YAML for parameters looks like this

    params:
      country: "Turkey"

Calling `params$country` in the R Markdown document will thus return `"Turkey"`. `yml_params()` will write this for you:

    yml() %>%
      yml_params(country = "Turkey")

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

You can also fill in parameters using a Shiny app with the “Knit with Parameters” button in the RStudio IDE or by passing `"ask"` to the `params` argument in `rmarkdown::render()`. While R Markdown will try to guess the Shiny widget type by the value of the parameter, you can specify them yourself with ymlthis functions that start with `shiny_*()`.

    yml() %>%
      yml_params(
        data = shiny_file("Upload Data (.csv)"),
        n = shiny_numeric("n to sample", 10),
        date = shiny_date("Date"),
        show_plot = shiny_checkbox("Plot the data?", TRUE)
      )

    ---
    author: Malcolm Barrett
    date: '`r format(Sys.Date())`'
    params:
      data:
        input: file
        label: Upload Data (.csv)
      'n':
        input: numeric
        label: n to sample
        value: 10.0
      date:
        input: date
        label: Date
      show_plot:
        input: checkbox
        label: Plot the data?
        value: true
    ---

## References and citations

R Markdown has excellent support for citations. The simplest way to use references in an R Markdown file is to add a bibliography file using the `bibliography` field.

    yml() %>%
      yml_citations(bibliography = "refs.bib")

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

However, if you only have a few references and want to keep your file self-contained, you can also specify references directly in your YAML using `yml_reference()` and `reference()`.

    ref <- reference(
      id = "fenner2012a",
      title = "One-click science marketing",
      author = list(
        family = "Fenner",
        given = "Martin"
      ),
      `container-title` = "Nature Materials",
      volume = 11L,
      URL = "https://doi.org/10.1038/nmat3283",
      DOI = "10.1038/nmat3283",
      issue = 4L,
      publisher = "Nature Publishing Group",
      page = "261-263",
      type = "article-journal",
      issued = list(
        year = 2012,
        month = 3
      )
    )

    yml() %>%
      yml_reference(ref)

    ---
    author: Malcolm Barrett
    date: '`r format(Sys.Date())`'
    reference:
    - id: fenner2012a
      title: One-click science marketing
      author:
        family: Fenner
        given: Martin
      container-title: Nature Materials
      volume: 11
      URL: https://doi.org/10.1038/nmat3283
      DOI: 10.1038/nmat3283
      issue: 4
      publisher: Nature Publishing Group
      page: 261-263
      type: article-journal
      issued:
        year: 2012.0
        month: 3.0
    ---

`yml_reference()` also supports package citation using the `.bibentry` argument and `citation()`.

    yml() %>%
      yml_reference(.bibentry = citation("purrr"))

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

If you have an existing `.bib` file, but you want to specify it in the YAML, instead, you can convert it with `bib2yml()`. For instance, if you wrote a `.bib` file for the packages used in your document with `knitr::write_bib()`, `bib2yml()` will translate the file to YAML you can include directly in the metadata.

# R Markdown extensions

Packages that extend R Markdown, such as bookdown and blogdown, also extend the YAML used to make documents. One of the main ways that other packages introduce YAML is through new output functions. xaringan, for instance, doesn’t use custom YAML outside of its output function, so ymlthis supports it out-of-box. Passing `xaringan::moon_reader()` to `yml_output()` will write the YAML for you.

    yml() %>%
      yml_title("Presentation Ninja") %>%
      yml_subtitle("with xaringan") %>%
      yml_output(
        xaringan::moon_reader(
          lib_dir = "libs",
          nature = list(
            highlightStyle = "github",
            highlightLines = TRUE,
            countIncrementalSlides = FALSE
          )
        )
      )

    ---
    author: Malcolm Barrett
    date: '`r format(Sys.Date())`'
    title: Presentation Ninja
    subtitle: with xaringan
    output:
      xaringan::moon_reader:
        lib_dir: libs
        nature:
          highlightStyle: github
          highlightLines: true
          countIncrementalSlides: false
    ---

ymlthis can process any output function. Other packages also add additional YAML; ymlthis supports six R Markdown packages: bookdown, blogdown, pkgdown, pagedown, rticles, and distill. ymlthis also supports YAML for writing scheduled emails with RStudio Connect. You can find functions supporting these packages with the patterns `yml_packagename_*()` and `packagename_*()` (`rsconnect`, in the case of RStudio Connect functions). Functions that start with `yml_packagename_*()` document YAML fields and return `yml` objects, while functions that start with `packagename_*()` are helper functions. There are also a few template functions. `pkgdown_template()`, for instance, will assemble a full template for `_pkgdown.yml` and return it as a `yml` object, and `blogdown_template()` will return YAML templates matching your Hugo theme.

Sources of YAML in R Markdown Extension
package | output function | top-level YAML
--- | --- | ---
bookdown | ✓ | ✓
blogdown | ✓ | ✓
pkgdown | ✓ | ✓
pagedown | ✓ | ✓
rticles | ✓ | ✓
distill | ✓ | ✓
learnr | ✓ | ✗
xaringan | ✓ | ✗
revealjs | ✓ | ✗
flexdashboard | ✓ | ✗

# R Markdown workflows

ymlthis prints YAML cleanly to the console such that you could copy and paste it into an R Markdown document. However, ymlthis also provides a number of other workflows.

### YAML add-in

The easiest way is to use the Shiny add-in included with ymlthis; the add-in supports the most commonly used R Markdown options, citations, LaTeX options, and parameterized reports. You can then export the YAML to an R Markdown file, YAML file, or have it placed on your clipboard.

For more flexibility or to use R Markdown extension packages, you’ll have to write code, as we’ve been doing in this vignette. Your main options are to write the YAML to a file or to place it on your clipboard.

### Writing to files

`use_rmarkdown()`, `use_yml_file()`, and friends will take a `yml` object and write to a file for you. Passing `yml` objects to `use_rmarkdown()` is often the simplest approach: it will translate the `yml` object into YAML and open a new R Markdown file for you with the metadata already written.

ymlthis also supports YAML files. For instance, using `pkgdown_template() %>% use_pkgdown_yml()` will write the YAML for your pkgdown site to `_pkgdown.yml` based on your package directory. ymlthis also has some helper functions for working with Pandoc templates and highlighting themes.

As an example, let’s set up the navbar YAML for an R Markdown website and then pass it to `use_navbar_yml()`.

    navbar_yaml <- yml_empty() %>%
      yml_site_opts(
        name = "my-website",
        output_dir =  "_site",
        include = "demo.R",
        exclude = c("docs.txt", "*.csv")
      ) %>%
      yml_navbar(
        title = "My Website",
        left = list(
          navbar_page("Home", href = "index.html"),
          navbar_page(navbar_separator(), href = "about.html")
        )
      ) %>%
      yml_output(html_document(toc = TRUE, highlight = "textmate"))

    # save to temporary directory since this is not interactive
    path <- tempfile()
    fs::dir_create(path)

    use_navbar_yml(navbar_yaml, path = path)
    #> ✔ Writing
    #>   '/private/var/folders/8v/gwyh3s5x5h7ddt4yj1m4p1440000gn/T/Rtmp8EYffy/filee76e6896d529/_navbar.yml'.

In addition to writing to files, you can save YAML to your `.Rprofile` using `options(ymlthis.defaults = "{YAML}")`. `yml()` will return the stored YAML by default. If you pass a `yml` object to `use_yml_defaults()`, the code to do this will be placed on your clipboard, which you should paste into your `.Rprofile`. Open that file with `usethis::edit_r_profile()`. You can also set a default for body text for `use_rmarkdown()` by setting the `ymlthis.rmd_body()` option, e.g. `options(ymlthis.rmd_body = "{your text}")` (or take advantage of `use_rmd_defaults()`). Together with specifying default YAML, `use_rmarkdown()` also serves as an ad-hoc way to make R Markdown templates.

    old <- options(
      ymlthis.default_yml = "author: Malcolm Barrett
    date: '`r format(Sys.Date())`'
    output: bookdown::pdf_document2",
      ymlthis.rmd_body = c(
        "",
        ymlthis::setup_chunk(),
        "",
        ymlthis::code_chunk(
          library(ymlthis)
        )
      )
    )

    #  use temporary path set above
    use_rmarkdown(path = file.path(path, "analysis.Rmd"))
    #> ✔ Writing
    #>   '/var/folders/8v/gwyh3s5x5h7ddt4yj1m4p1440000gn/T/Rtmp8EYffy/filee76e6896d529/analysis.Rmd'.

    # reset previous option defaults
    options(old)

ymlthis `use_*()` functions to write to `.yml` files
function | action
--- | ---
`use_yml_file()` | Write `yml` to a file
`use_bookdown_yml()` | Write `yml` to `_bookdown.yml`
`use_navbar_yml()` | Write `yml` to `_navbar.yml`
`use_output_yml()` | Write `yml` to `_output.yml`
`use_pkgdown_yml()` | Write `yml` to `_pkgdown.yml`
`use_site_yml()` | Write `yml` to `_site.yml`

ymlthis `use_*()` to write to `.Rmd` files
function | action
--- | ---
`use_rmarkdown()` | Write `yml` to a `.Rmd` file
`use_index_rmd()` | Write `yml` to `Index.Rmd`

### Placing YAML on your clipboard

A final way to use ymlthis is to put YAML on your clipboard to paste into a file or other setting. To place rendered YAML on your clipboard, simply pass a `yml` object to `use_yml()`.

Additional ymlthis `use_*()` functions
function | action
--- | ---
`use_yml()` | Place `yml` on your clipboard
`use_yml_defaults()` | Place code on your clipboard to save `yml` to your default options
`use_pandoc_highlight_style()` | Write pandoc theme templates to a `.theme` file
`use_pandoc_template()` | Write pandoc templates to a file

# Working with yml objects

Under the hood, `yml` objects are lists of types that match the corresponding YAML and are only converted to YAML when printing or writing to files. Because `yml` objects are just lists, you can work with them as such. ymlthis also includes several purrr-like functions for working with `yml` objects. Let’s define a `yml` object that has a fairly comprehensive set of options:

    x <-
      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")
        ),
        html_document()
      ) %>%
      yml_latex_opts(biblio_style = "apalike")

The resulting YAML of `x` is:

    ---
    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
      html_document: default
    biblio-style: apalike
    ---

We can use `yml_discard()` to remove the `category` option:

    x %>%
      yml_discard("category")

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

We can use purrr-style lambdas to express what to discard. How about any YAML fields with a length greater than one?

    x %>%
      yml_discard(~ length(.x) > 1)

    ---
    date: 07/04/2019
    title: Reproducible Research in R
    biblio-style: apalike
    ---

The `yml_pluck()` function is useful for selectively acquiring a nested portion of the YAML:

    x %>%
      yml_pluck("output", "pdf_document")

    ---
    keep_tex: true
    includes:
      after_body: footer.tex
    ---