18.2 Fully custom formats

Another lower-level approach is to define a format directly by explicitly specifying knitr options and Pandoc command-line arguments. At its core, an R Markdown format consists of:

  1. A set of knitr options that govern how Rmd is converted to Markdown.

  2. A set of Pandoc options that govern how Markdown is converted to the final output format (e.g., HTML).

  3. Some optional flags and filters (typically used to control handling of supporting files).

You can create a new format using the output_format() function in rmarkdown. Here is an example of a simple format definition:

#' @importFrom rmarkdown output_format knitr_options pandoc_options
simple_html_format = function() {
  # if you don't use roxygen2 (see above), you need to either
  # library(rmarkdown) or use rmarkdown::
  output_format(
    knitr = knitr_options(opts_chunk = list(dev = 'png')),
    pandoc = pandoc_options(to = "html"),
    clean_supporting = FALSE
  )
}

The knitr and Pandoc options can get considerably complicated (see help pages ?rmarkdown::knitr_options and ?rmarkdown::pandoc_options for details). The clean_supporting option indicates that you are not creating self-contained output (like a PDF or HTML document with base64 encoded resources), and therefore want to preserve supporting files like R plots generated during knitting.

You can also pass a base_format to the output_format() function if you want to inherit all of the behavior of an existing format but tweak a subset of its options.

If there are supporting files required for your format that cannot be easily handled by the includes option (see Section 3.1.10.2), you will also need to use the other arguments to output_format to ensure they are handled correctly (e.g., use the intermediates_generator to copy them into the place alongside the generated document).

The best way to learn more about creating fully custom formats is to study the source code of the existing built-in formats (e.g., html_document and pdf_document): https://github.com/rstudio/rmarkdown/tree/master/R. In some cases, a custom format will define its own Pandoc template, which was discussed in Section 17.3.