Enrich the YAML headers of README.Rmd and vignettes/*.Rmd of a package

Applies optimize_rmd_yaml() to README.Rmd and every .Rmd under vignettes/, with a progress bar. See optimize_rmd_yaml() for the compatibility rules and the meaning of the shared arguments.

Usage

package_optimize_rmd_yaml(
  path = NULL,
  readme = TRUE,
  vignettes = TRUE,
  readme_format = c("gfm", "github_document", "html"),
  date = c("auto", "desc", "none"),
  extra = NULL,
  extra_readme = NULL,
  extra_vignette = NULL
)

Arguments

path

Package root directory. NULL means the current directory.

readme

Process README.Rmd?

vignettes

Process .Rmd files in vignettes/?

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

The paths of the files that were changed (invisibly).

Examples

if (FALSE) { # \dontrun{
package_optimize_rmd_yaml()
package_optimize_rmd_yaml(readme_format = "github_document", date = "desc")

package_optimize_rmd_yaml(
  extra = list(lang = "zh-CN"),                   # merged with the defaults
  extra_readme = list(always_allow_html = NULL),  # drop a README default
  extra_vignette = list(
    bibliography = "refs.bib",
    `link-citations` = TRUE,
    params = list(eval = FALSE)
  )
)
} # }