Skip to contents

Enrich the YAML header of ONE Rmd file using the package DESCRIPTION

Source: R/10_optimize_rmd_yaml.R
optimize_rmd_yaml.Rd

Optimizes the YAML header of a single README.Rmd or vignette. Package metadata (Package / Title / Version / Authors@R / Date / Language) is read with the desc package from the DESCRIPTION found by walking up from path.

Usage

optimize_rmd_yaml(
  path = NULL,
  type = c("auto", "readme", "vignette"),
  readme_format = c("gfm", "github_document", "html"),
  date = c("auto", "desc", "none"),
  extra = NULL,
  extra_readme = NULL,
  extra_vignette = NULL
)

Arguments

path

Path to an Rmd file. If NULL, the file open in the active RStudio editor is used.

type

"auto" (README.Rmd is a readme, everything else a vignette), "readme" or "vignette".

readme_format

Format used when a README has the default output: "gfm" (md_document + variant: gfm), "github_document" or "html".

date

"auto" -> Sys.Date(); "desc" -> DESCRIPTION Date field; "none" -> do not add a date.

extra

Named list of extra YAML fields added to the file. It is merged onto the built-in defaults with utils::modifyList() (nested lists are merged recursively, your values win). Built-in default: RStudio editor_options (markdown: wrap: sentence, chunk_output_type: console). To drop a default, set it to NULL, e.g. list(editor_options = NULL).

extra_readme, extra_vignette

Same as extra, but only applied when the file is a README / a vignette. Merge order (later wins): built-in defaults -> extra -> extra_readme / extra_vignette. Built-in README default: always_allow_html: true.

Extra fields never overwrite a key that already exists in the header; they are only added when missing. A key that is also generated by default (e.g. lang, date, author) replaces the generated value.

Value

TRUE if the file was changed, FALSE otherwise (invisibly).

Details

Compatibility rules (the usethis template is treated as the "default"):

  • A field that still has its usethis default value (title "Untitled" or equal to the file name, a bare output: html_document / output: rmarkdown::html_vignette, an "Untitled" VignetteIndexEntry) is replaced by an enriched value.

  • A field the user has changed is kept. For output, the user's options are merged on top of the enriched defaults (user values always win), and other output formats (pdf_document, word_document, ...) are left untouched.

  • Fields that usethis never writes (author, date, params, bibliography, knit, css, ...) are kept exactly as written when present, and only filled in when missing.

  • Headers containing !expr in output are never rewritten.

Examples

if (FALSE) { # \dontrun{
optimize_rmd_yaml()                          # active RStudio document
optimize_rmd_yaml("vignettes/intro.Rmd")
optimize_rmd_yaml("README.Rmd", readme_format = "github_document")
} # }