Using Word Reference Documents with RMarkdown to Create Custom Reports

Defaults are the worst. See this plot?

The default ggplot look

If you see a plot that looks like this, you know two things:

  1. It’s made with ggplot
  2. The person who made it didn’t even take the time to change any of the defaults

Don’t settle for defaults! It’s one of the messages I discuss throughout the data visualization section of my Going Deeper with R course.

Avoiding defaults is also something you can with RMarkdown as well. When you knit an RMarkdown document to Word, it takes on the default styles in Word. On my Mac with Word 2016, it looks like this:

The default Word look

Fortunately, it’s really easy to avoid using this default using what’s known as reference documents. To change the styles of your headers, paragraph text, etc, do the following:

Create a reference Word document with the styles you want to use.

Add a line in your YAML that tells RMarkdown where to find the reference document you just created like this:


Now, when you open your Word document, it will use the styles you created. Curious to see how this works? This video from Going Deeper with R (which also explains the “Your Turn” section at the end) walks through the process of using Word reference documents with RMarkdown.

Interested in learning more? In addition to signing up for Going Deeper with R, I’d recommend this article by Rose-Hulman Institute of Technology’s Richard Layton. It was written in 2015, but is still relevant today. I also recommend the first five or so minutes of this 2018 talk by Daniel Hadley of the Sorensen Impact Center.