Define and merge an R Markdown's output format dependency

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.

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

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).

Value

An list of arguments with the "rmd_dependency" class.

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")
)
#> $name
#> [1] "lua_filter1"
#> 
#> $knitr
#> NULL
#> 
#> $pandoc
#> $pandoc$lua_filters
#> [1] "example1.lua"
#> 
#> 
#> $pre_processor
#> NULL
#> 
#> $keep_md
#> NULL
#> 
#> $clean_supporting
#> NULL
#> 
#> $post_processor
#> NULL
#> 
#> $file_scope
#> NULL
#> 
#> $on_exit
#> NULL
#> 
#> attr(,"class")
#> [1] "output_format_dependency"

# Explicitly add lua filters from within a chunk
knitr::knit_meta_add(list(output_format_dependency(
  "lua_filter2",
  pandoc = list(lua_filters = "example2.lua")
)))
#> [[1]]
#> $name
#> [1] "lua_filter2"
#> 
#> $knitr
#> NULL
#> 
#> $pandoc
#> $pandoc$lua_filters
#> [1] "example2.lua"
#> 
#> 
#> $pre_processor
#> NULL
#> 
#> $keep_md
#> NULL
#> 
#> $clean_supporting
#> NULL
#> 
#> $post_processor
#> NULL
#> 
#> $file_scope
#> NULL
#> 
#> $on_exit
#> NULL
#> 
#> attr(,"class")
#> [1] "output_format_dependency"
#> 
#> attr(,"knit_meta_id")
#> [1] ""

# 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))
#> List of 1
#>  $ :List of 9
#>   ..$ name            : chr "lua_filter2"
#>   ..$ knitr           : NULL
#>   ..$ pandoc          :List of 1
#>   .. ..$ lua_filters: chr "example2.lua"
#>   ..$ pre_processor   : NULL
#>   ..$ keep_md         : NULL
#>   ..$ clean_supporting: NULL
#>   ..$ post_processor  : NULL
#>   ..$ file_scope      : NULL
#>   ..$ on_exit         : NULL
#>   ..- attr(*, "class")= chr "output_format_dependency"