Render a Quarto or Bookdown project after processing the bookmarks

These functions take a Quarto or Bookdown project, extract all bookmarked data, run all bookmark functions, optionally select one or more chapters, and then return the result in an bm_prepared_book object (bookmark::bm_prepare) or render (bookmark::bm_render()) the resulting book.

Usage

bm_prepare(
  x,
  idsToSelect = NULL,
  idsToSelectRegex = NULL,
  includeDependencies = TRUE,
  functionArgs = list(),
  functionList = list(),
  filterFunction = NULL,
  filterFunArgs = NULL,
  includeFiles = c("\\.rmd", "\\.qmd", "\\.md"),
  includeDirs = NULL,
  excludeFiles = NULL,
  excludeDirs = NULL,
  dependencies = list(id = "metadata", key = "dependency"),
  forceIndexInclusion = TRUE,
  clean = TRUE,
  ignore.case = TRUE,
  perl = TRUE,
  configFilenames = bookmark::opts$get("configFilenames"),
  encoding = bookmark::opts$get("encoding"),
  silent = bookmark::opts$get("silent")
)

bm_render(
  x,
  output,
  idsToSelect = NULL,
  idsToSelectRegex = NULL,
  includeDependencies = TRUE,
  functionArgs = list(),
  functionList = list(),
  filterFunction = NULL,
  filterFunArgs = NULL,
  includeFiles = c("\\.rmd", "\\.qmd", "\\.md"),
  includeDirs = NULL,
  excludeFiles = NULL,
  excludeDirs = NULL,
  dependencies = list(id = "metadata", key = "dependency"),
  forceIndexInclusion = TRUE,
  open = TRUE,
  clean = TRUE,
  ignore.case = TRUE,
  perl = TRUE,
  configFilenames = bookmark::opts$get("configFilenames"),
  encoding = bookmark::opts$get("encoding"),
  silent = bookmark::opts$get("silent")
)

Arguments

x: Either the directory holding the Quarto or Bookdown project (that directory must then contain a configuration file, by default named _quarto.yml or _bookdown.yml - see the configFilenames argument), or a bm_prepared_book object, the result of a call to bookmark::bm_prepare().
idsToSelect: Optionally, a character vector with one or more chapter identifiers. Chapter identifiers are specified in each file by including , where identifier is the file's unique identifier (starting with a letter ([a-zA-Z]) and only containing letters, (Arabic) digits, and underscores).
idsToSelectRegex: Instead of specifying chapter identifiers to select, you can also specify a regular expression, which is then matched against all chapters (and only those matching the regular expression are selected).
includeDependencies: Whether to also include all chapters that are dependencies of the selected chapters. Dependencies are specified as bookmarks with the identifier and key that are passed in the dependencies argument (by default, identifier metadata and key dependency). If includeDependencies = TRUE, each chapter's dependency tree is built and all (direct and indirect) dependencies are also included in the list of selected chapters.
functionArgs: Additional arguments to pass to each function as a named list of named lists. The names of the lists passed in the functionArgs list are the names of the functions the arguments should be passed to, and the names of the elements of each such list are the argument names for that function (e.g. passing functionArgs=list(paste=list(collapse='\n')) would add collapse='\n' to every bookmark-processing call to paste0). These arguments are always overridden by any arguments specified in the bookmark fragments in the file.
functionList: A named list of funtions. When a function is specified in a bookmark fragment, it is first sought in this functionList, and if not found there, get0() is used to try to find it.
filterFunction: A function to filter chapters. Like idsToSelect, idsToSelectRegex, and includeDependencies, this can be used to select chapters to include in the final book. Like regular functions called by bookmark, it must have at least two arguments: x and id, where as x, the object with processed bookmark files (i.e., book chapters) will be passed, and as id, the identifier of the currently processed chapter.
filterFunArgs: Any additional arguments to pass to the filterFunction.
includeFiles: A regular expression to select files to include out of the list of files in directory x.
includeDirs: A regular expression to select subdirectories to include out of the list of directories in directory x.
excludeFiles: A regular expression to select files to exclude out of the list of files in directory x. Files are excluded after the inclusion regular expression has been applied, to any files matching this regular expression are excluded.
excludeDirs: A regular expression to select subdirectories to exclude out of the list of directories in directory x. Directories are excluded after the inclusion regular expression has been applied, to any directories matching this regular expression are excluded.
dependencies: If includeDependencies=TRUE, this list specifies the identifier and key that hold the dependencies for a given chapter (see the includeDependencies argument).
forceIndexInclusion: Whether to force inclusion of the index.*md file, a requirement of Bookdown and Quarto. This can be convenient to easily specify the desired chapters using a regular expression, without having to adjust for the index file.
clean: Whether to clean the files (remove the comments holding the bookmarks).
ignore.case, perl: These are passed to the regular expression functions (see, for example, grep()_).
configFilenames: The regular expression(s) to use to find the configuration files. It is a named vector where the names are the rendering packages (currently "quarto" or "bookmark" are valid), and the values are the filenames.
encoding: The encoding to use when reading and writing files.
silent: Whether to be silent (TRUE) or emit more logging info (FALSE).
output: The directory to write the final rendered book to.
open: Whether to immediately open the rendered book in the RStudio viewer (will throw a warning if rstudioapi is not installed).

Value

The prepared book as a bm_prepared_book object (invisibly).

Details

Typically, bookmark books are read from a directory and then placed in a bookmarks_from_dir object, which is then prepared and stored in a bm_prepared_book object, which can then be rendered to a book.