18.2 Fully custom formats

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

  1. A set ofknitr 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 theoutput_format() function inrmarkdown. Here is an example of a simple format definition:

#' @importFrom rmarkdown output_format knitr_options pandoc_optionssimple_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  )}

Theknitr and Pandoc options can get considerably complicated (see help pages?rmarkdown::knitr_options and?rmarkdown::pandoc_options for details). Theclean_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 abase_format to theoutput_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 theincludes option (see Section3.1.10.2), you will also need to use the other arguments tooutput_format to ensure they are handled correctly (e.g., use theintermediates_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 andpdf_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 Section17.3.