RStudio IDE

Customizing Markdown Rendering

Overview

The Knit HTML command in RStudio performs two discrete operations:

  1. Knits the .Rmd file into a plain markdown (.md) file. This involves executing all of the R code chunks and inserting the appropriate output into the markdown file.
  2. Renders the markdown file into HTML.

By default, the second step (markdown rendering) is equivalent to calling the markdownToHTML function of the markdown package with all of its default arguments (the specifics of this are described more fully in the R Markdown article).

It is however possible to customize this behavior by providing an alternate markdownToHTML function. This article describes how to do this as well as examples for some common customizations.

Providing a Rendering Function

A custom markdown rendering function is established by setting the rstudio.markdownToHTML global option. The semantics and behavior of this function are as follows:

  • If provided, the function will be run in place of the default RStudio markdown rendering.
  • During the execution of the function the working directory will always be set to the directory containing the markdown source file being processed.
  • The function accepts two arguments: the markdown input file to process and the HTML output file to write to. Note that the file paths are relative to the directory containing the input file rather than absolute.

For example, the following code installs a custom rendering function that has behavior equivalent to the RStudio default:

options(rstudio.markdownToHTML = 
  function(inputFile, outputFile) {      
    require(markdown)
    markdownToHTML(inputFile, outputFile)   
  }
)

This example makes use of the markdown package. If you want to use the markdown package in your own custom rendering function you'll need to install it explicitly (RStudio shares code with the markdown package but doesn't install it).

Global vs. Project Level Customization

If you want to globally override markdown rendering, the recommended approach is to set the rstudio.markdownToHTML option within the global .Rprofile file (e.g. ~/.Rprofile).

If on the other hand you want to customize markdown rendering only for a specific project or working directory, then the option should be defined within an .Rprofile file within the project working directory (see this article on R Startup for more details on the handling of .Rprofile files).

If you need to customize rendering for just a specific file, you can also simply write an R script that sets the appropriate rendering function and then execute it prior to working with that file. Note that resetting the rstudio.markdownToHTML option to NULL will restore RStudio's default behavior.

Example Customizations

Custom CSS

You may wish to provide your own CSS stylesheet. You could do this with the following code:

options(rstudio.markdownToHTML = 
  function(inputFile, outputFile) {      
    require(markdown)
    markdownToHTML(inputFile, outputFile, stylesheet='custom.css')   
  }
) 

Note that in this example we assume that the file 'custom.css' is in the same directory as the input file. If it's located elsewhere in the filesystem you'll want to specify it's full path.

The default CSS used by RStudio for markdown rendering can be found here: RStudio Markdown CSS.

Overriding Default Options

You may like most of the default rendering provided by RStudio however wish to add or remove selected options. The following example removes the base64_images HTML option:

options(rstudio.markdownToHTML = 
  function(inputFile, outputFile) {      
    require(markdown)
    htmlOptions <- markdownHTMLOptions(defaults=TRUE)
    htmlOptions <- htmlOptions[htmlOptions != "base64_images"]
    markdownToHTML(inputFile, outputFile, options = htmlOptions) 
  }
) 

You can read more about the various available options within the documentation of the markdown package.

Using Pandoc

The above examples illustrated customizing the behavior of the markdown package. It's also possible to use another markdown rendering engine entirely. For example, to use Pandoc you could use the following code:

options(rstudio.markdownToHTML = 
  function(inputFile, outputFile) {      
    system(paste("pandoc", shQuote(inputFile), "-o", shQuote(outputFile)))
  }
)  

This example is of course highly simplified and you'll likely want to specify additional command-line options.

When deciding whether to use an alternate engine like Pandoc, it's important to keep in mind that R markdown features like MathJax equations, image embedding, and R syntax highlighting won't be automatically present. There are of course ways to do all of these things in Pandoc but they aren't the default behavior so additional customization will be required.

For more information on using Pandoc see the Pandoc web site.

 

Related Topics