18.1 Deriving from built-in formats

The easiest way to create a new format is to write a function that calls one of the built-in formats. These built-in formats are designed to be extensible enough to serve as the foundation of custom formats. The following example, quarterly_report, is based on html_document but alters the default options:

quarterly_report = function(toc = TRUE) {
  # locations of resource files in the package
  pkg_resource = function(...) {
    system.file(..., package = "mypackage")
  }

  css    = pkg_resource("reports/styles.css")
  header = pkg_resource("reports/quarterly/header.html")

  # call the base html_document function
  rmarkdown::html_document(
    toc = toc, fig_width = 6.5, fig_height = 4,
    theme = NULL, css = css,
    includes = rmarkdown::includes(before_body = header)
  )
}

The new format defined has the following behavior:

1. Provides an option to determine whether a table of contents should be generated (implemented by passing toc through to the base format).

2. Sets a default height and width for figures (note that this is intentionally not user-customizable so as to encourage a standard for all reports of this type).

3. Disables the default Bootstrap theme and provides custom CSS in its place.

4. Adds a standard header to every document.

Note that (3) and (4) are implemented using external files that are stored within the package that defines the custom format, so their locations need to be looked up using the system.file() function.