Skip to contents

Tools for README & Documentation

rpkgkit 0.1.23

Yuxi Yang

2026-11-06

Source: vignettes/readme_and_doc.Rmd
readme_and_doc.Rmd
library(rpkgkit)
dir <- file.path(tempdir(), "example")
usethis::create_package(dir, open = FALSE)
usethis::local_project(dir)
usethis::use_readme_md(open = FALSE)

Manage README translations

use_multilanguage_readme() creates translation placeholders below inst/translations/ and prints Markdown badges that link to them.

This will help you plan a good structure for multilingual README files.

Badge management

Insert badge strings into README

badge_to_readme() inserts one Markdown badge into the block delimited by <!-- badges: start --> and <!-- badges: end -->. When both README files exist, it updates README.Rmd rather than the generated README.md.

Usually you can adds a badge generated by badger + badge_to_readme()

A badge may also be supplied directly as a single Markdown string:

badge_to_readme(
  "[![R-CMD-check](https://example.com/check.svg)](https://example.com)",
  path = dir
)
readLines("README.md") |> cli::cli_code()

If the exact badge is already present, the function leaves the file unchanged.

Badge for AI-translated README files

badge_translated_by_ai() prints a badge and disclosure statement for AI-translated README files.

badge_translated_by_ai("es")
#> ☐ Consider copying the following statement to the AI-translated file(s):
#> 
#> 
#> [![AI](https://img.shields.io/badge/AI-Espa%C3%B1ol-yellow)]()
#> 
#> 
#> 
#> > Este contenido ha sido traducido por IA y no ha sido revisado. No es la lengua materna del autor y es solo para referencia.

Enrich Rmd YAML headers

optimize_rmd_yaml() rewrites the YAML header of one README.Rmd or vignette from the package DESCRIPTION: title, subtitle, author, date, lang, an enriched output block and, for vignettes, the VignetteIndexEntry.

Fields that still hold their usethis default value (an "Untitled" title, a bare output: rmarkdown::html_vignette) are replaced, fields you have changed are kept, and your output options are merged on top of the enriched defaults.

optimize_rmd_yaml() # active RStudio document
optimize_rmd_yaml("vignettes/intro.Rmd")
optimize_rmd_yaml("README.Rmd", readme_format = "github_document")

package_optimize_rmd_yaml() applies the same logic to README.Rmd and every .Rmd below vignettes/:

Both functions accept extra, extra_readme and extra_vignette to add your own fields (merged recursively, later values win) and to drop a built-in default with NULL. date = "desc" reuses the DESCRIPTION date instead of Sys.Date():

package_optimize_rmd_yaml(
  path = dir,
  date = "desc",
  extra = list(lang = "zh-CN"),
  extra_readme = list(always_allow_html = NULL),
  extra_vignette = list(bibliography = "refs.bib", `link-citations` = TRUE)
)

Each function returns invisibly whether (or which files) it changed, so it is safe to run on every build.