rmarkdown (version 2.28)

output_format_dependency: Define and merge an R Markdown's output format dependency

Description

Define and merge a dependency such as pre/post-processors from within chunks. The merge happens explicitly when a list of dependencies are passed to knitr::knit_meta_add() or implicitly when a dependency is knitr::knit_printed. Defining a function that does the former is the best way for package developers to share the dependency. On the contrary, the latter is useful to declare a document-specific dependency. This function shares some arguments with output_format, but lacks the others because dependency is resolved after post_knit and before pre_processor.

Usage

output_format_dependency(
  name,
  pandoc = list(),
  pre_processor = NULL,
  post_processor = NULL,
  file_scope = NULL,
  on_exit = NULL
)

Value

An list of arguments with the "rmd_dependency" class.

Arguments

name

A dependency name. If some dependencies share the same name, then only the first one will be merged to the output format.

pandoc

Pandoc options for an output format (see pandoc_options)

pre_processor

An optional pre-processor function that receives the metadata, input_file, runtime, knit_meta, files_dir, and output_dir and can return additional arguments to pass to pandoc.

post_processor

An optional post-processor function that receives the metadata, input_file, output_file, clean, and verbose parameters, and can return an alternative output_file.

file_scope

A function that will split markdown input to pandoc into multiple named files. This is useful when the caller has concatenated a set of Rmd files together (as bookdown does), and those files may need to processed by pandoc using the --file-scope option. The first argument is input file paths and the second is NULL or current file scope which is a named list of files w/ name and content for each file. The return is the new file scope. Also, the arguments should include ... for the future extensions.

on_exit

A function to call when rmarkdown::render() finishes execution (as registered with a on.exit handler).

Examples

# Implicitly add lua filters from within a chunk
# This relies on (implicit) printing of the dependency in a chunk via
# knitr::knit_print()`
output_format_dependency(
  "lua_filter1",
  pandoc = list(lua_filters = "example1.lua")
)

# Explicitly add lua filters from within a chunk
knitr::knit_meta_add(list(output_format_dependency(
  "lua_filter2",
  pandoc = list(lua_filters = "example2.lua")
)))

# List the available dependencies
# Note that the list may include dependencies with duplicated names. In that
# case, the first one is merged to the output format and the others are
# discarded.
str(knitr::knit_meta("output_format_dependency", clean = FALSE))