Theming HTML Reports with R Markdown

R Markdown creates professional HTML reports by default, but the default appearance may not match your brand or preferences. You can customize HTML reports using built-in themes, additional theme packages, or custom CSS. This tutorial shows you how to make your reports look exactly how you want them.

Using Built-in Themes

R Markdown includes several built-in themes for HTML documents. These themes control fonts, colors, and overall styling. You specify a theme in the YAML header using the theme option:

---
output:
  html_document:
    theme: united
---

The available built-in themes are: default, bootstrap, cerulean, journal, flatly, readable, spacelab, united, and lumen.

Each theme has a distinct look. cerulean gives a clean, blue-toned appearance similar to Bootstrap. journal mimics the style of academic journals with a serif font. flatly provides a modern, flat design with good contrast. readable creates a dark-mode report. lumen is an expansive, modern theme with generous whitespace.

Here is how to apply the cosmo theme:

---
output:
  html_document:
    theme: cosmo
---

When you knit this document, R Markdown applies the selected theme to the entire HTML output. The theme affects headings, body text, code blocks, tables, and navigation elements.

Highlighting Code with Highlight Styles

Along with the page theme, you can specify a code highlighting style. This controls how R code chunks and their syntax appear in the rendered document:

---
output:
  html_document:
    theme: flatly
    highlight: tango
---

Available highlight styles include: default, tango, pygments, kate, monochrome, espresso, zenburn, and haddock. The tango style uses orange and blue syntax coloring. pygments is the classic Pygments scheme. zenburn provides a dark, low-contrast theme popular in the R community.

The rmdformats Package

The rmdformats package provides additional HTML output formats with pre-built styling. It includes themes like html_clean, docco, and readthedown that offer different layouts and visual styles.

Install the package first:

install.packages("rmdformats")

Then use one of its output formats in your YAML:

---
output: rmdformats::html_clean
---

The html_clean format produces a clean, minimalist design with automatic table of contents. The docco format resembles the Docco documentation style with code on the left and comments on the right. The readthedown format provides a responsive design optimized for mobile viewing.

The rmdformats package also includes the html_docco format, which creates beautiful documentation-style pages:

---
output: rmdformats::html_docco
---

This format adds a navigation sidebar, supports image lightboxes, and includes syntax highlighting. It works well for package documentation, long-form reports, and tutorials.

Customizing with CSS

For complete control, you can add custom CSS to override any theme styling. Create a CSS file or include CSS directly in your document:

---
output:
  html_document:
    theme: flatly
    css: styles.css
---

Alternatively, include CSS inline using the includes option:

---
output:
  html_document:
    includes:
      in_header: header.html
---

A simple custom stylesheet might look like this:

body {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
  font-size: 16px;
  line-height: 1.6;
}

h1, h2, h3 {
  color: #2c3e50;
  border-bottom: 1px solid #eee;
  padding-bottom: 10px;
}

.navbar {
  background-color: #3498db !important;
}

pre {
  background-color: #f8f8f8;
  border: 1px solid #ddd;
  border-radius: 4px;
}

This CSS changes the body font, adds colored borders under headings, customizes the navigation bar, and modifies code block background colors.

Changing Fonts

You can change fonts by adding CSS rules. First, include the Google Fonts stylesheet in your document header:

---
output:
  html_document:
    includes:
      in_header: google_fonts.html
    theme: flatly
---

Create the google_fonts.html file:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lato:wght@400;700&family=Merriweather:wght@400;700&display=swap">
<style>
  body {
    font-family: 'Lato', sans-serif;
  }
  h1, h2, h3, h4, h5, h6 {
    font-family: 'Merriweather', serif;
  }
</style>

This loads Lato and Merriweather from Google Fonts and applies them to your document. The combination of a sans-serif body font with serif headings creates a readable, professional appearance.

Adding a Logo and Custom Navigation

You can add a company logo to the navigation bar using the navbar option in your YAML:

---
output:
  html_document:
    theme: flatly
    include:
      navbar:
        left:
          - text: "My Company"
            href: "https://example.com"
        right:
          - text: "Documentation"
            href: "/docs"
---

This adds your logo to the top-left of the navigation bar and custom links on both sides. The navigation bar adapts to the theme colors automatically.

Complete Example: Branded Report

Here is a complete example bringing together several customizations:

---
title: "Sales Report Q4 2025"
author: "Data Team"
date: "`r Sys.Date()`"
output:
  html_document:
    theme: cosmo
    highlight: tango
    code_folding: show
    toc: true
    toc_float: true
    css: custom.css
    includes:
      in_header: google_fonts.html
---

library(ggplot2)
library(dplyr)
library(rmdformats)

# Set knitr options
knitr::opts_chunk$set(echo = TRUE, fig.align = "center")

The code_folding: show option adds buttons to hide or show R code chunks. The toc: true creates a table of contents, and toc_float: true makes it float as you scroll.

Summary

R Markdown provides multiple ways to customize HTML report appearance:

1. Built-in themes: Add theme: name to change the overall look
2. Highlight styles: Add highlight: style for code syntax coloring
3. rmdformats package: Provides additional professionally-designed formats
4. Custom CSS: Override any styling with your own CSS rules
5. Google Fonts: Load custom fonts for unique typography
6. Navigation customization: Add logos and custom links to the navbar

Start with a built-in theme that closely matches your needs, then refine with custom CSS. This approach gives you professional results without spending time on extensive customization.

Continue to the next tutorial in this series to learn about Building Dashboards with Quarto.