Including styles the quick, dirty and risky way

The fastest way to include a custom css stored in a file is to simply include a line like the following at the beginning of the R script that we are using spin() on:

#' <link rel="stylesheet" type="text/css" href="path-to-our.css">

This simple approach however has many caveats, as the line is just inserted into the body of the document within a paragraph, completely oblivious to what else was inserted. Unless there is a very good reason, we should use one of the safer and more robust approaches mentioned below.

Under the spin’s hood

Under the hood, spin() calls knit2html(), which passes many useful arguments to markdownToHTML(), the function that actually converts a markdown file to the final HTML format. Unfortunately, many of those useful arguments are not exposed via spin().

Bearing this in mind, we have a few ways to access and provide them with the desired values:

1. Changing the options that govern the default values and just call spin() as before
2. Perform the spinning in 2 steps

Changing the options that govern the default values and just call spin() as before

As mentioned above, spin() does not expose the arguments of markdownToHTML() directly, so what happens in practice is that the default values for those arguments are used when spin() is called. Some of the interesting arguments are by default selected in the following way:

options = getOption("markdown.HTML.options"), 
extensions = getOption("markdown.extensions") 
stylesheet = getOption("markdown.HTML.stylesheet")
template = getOption("markdown.HTML.template")

Let’s have a look at some interesting default options’ values:

library(markdown)
options()[c(
  "markdown.HTML.options",
  "markdown.extensions",
  "markdown.HTML.stylesheet"
)]

## $markdown.HTML.options
## [1] "use_xhtml"      "smartypants"    "base64_images"  "mathjax"       
## [5] "highlight_code"
## 
## $markdown.extensions
## [1] "no_intra_emphasis" "tables"            "fenced_code"      
## [4] "autolink"          "strikethrough"     "lax_spacing"      
## [7] "space_headers"     "superscript"       "latex_math"       
## 
## $markdown.HTML.stylesheet
## [1] "/usr/local/lib/R/site-library/markdown/resources/markdown.css"

If we want to keep the spinning in one step, we can simply update those options before calling spin (and ideally change them back afterwards). For a somewhat minimalistic HTML output still keeping images self-contained, we can do:

options(
  markdown.extensions = "fenced_code",
  markdown.HTML.options = "base64_images",
  markdown.HTML.stylesheet = "{}"
)
knitr::spin("spin_exaple.R")

To use a custom css stylesheet instead of the one provided by default with the markdown package:

options(markdown.HTML.stylesheet = "path_to_custom.css")
knitr::spin("path-to-r-script.R")

Perform the report creation in 2 steps

The method above works but can seem quite workaround-ish. The method that could be considered more proper is to actually split the production of the final output into 2 steps:

1. Generate an intermediate .Rmd file via spin(), using spin(..., knit = FALSE)
2. Run knit2html() on the created .Rmd file with the desired options directly specified as arguments

This allows us to provide additional arguments extensions, stylesheet, header, template and encoding in the second step, instead of relying on the changed options to be passed as defaults.

The below example will embed styles present in path_to_custom.css into the resulting HTML:

# Creates the intermediate path-to-r-script.Rmd
knitr::spin("path-to-r-script.R", knit = FALSE)

# Now create the final HTML output from
# path-to-r-script.Rmd, with desired options
knitr::knit2html(
  input = "path-to-r-script.Rmd",
  stylesheet = "path_to_custom.css"
)

Using both of the above options will actually embed the css directly into the HTML output that is produced, making the output larger in size.

Note that the arguments we are looking to provide to knit2html() are implemented as part of ..., so we will have to name them. To look at the details, study the documentation of markdownToHTML(), to which those arguments get passed.

spin with custom air.css

The output_format powerhouse

The output of render() is governed mainly by the output_format argument. Most of the time users will pass on just the name of the format, such as "html_document", as most of the options are governed by the yaml metadata present at the beginning of our Rmd files.

For R scripts we usually do not use the yaml metadata. In this case, we can take full advantage of the flexibility of that argument, passing a call to rmarkdown::html_document() with the desired parameters as output_format.

Minimalistic output with render()

To produce a minimalistic HTML output from our path-to-r-script.R script, we can for example specify the following as output_format:

rmarkdown::render(
  "path-to-r-script.R", 
  output_format = rmarkdown::html_document(
    theme = NULL,
    mathjax = NULL,
    highlight = NULL
  )
)

Custom css with render()

Including a custom css stylesheet is equally simple, just provide a css argument with the css file path to the html_document() function:

rmarkdown::render(
  "path-to-r-script.R", 
  output_format = rmarkdown::html_document(
    theme = NULL,
    mathjax = NULL,
    highlight = NULL,
    css = "path_to_custom.css"
  )
)

An interesting property of including custom css styles is that by default the argument self_contained is set to TRUE, meaning that the full stylesheet will be embedded into the output HTML file, including all the external css imported into the one we are using. This means that if your stylesheets import external fonts such as the following, those will also be pasted directly into the output:

@import url(http://fonts.googleapis.com/css?family=Open+Sans:300italic,300);

This behavior is different for spin(), which will paste the @import clause into the output as-is, instead of parsing and pasting the actual content of the provided url.