Fast Rmarkdown Theming with thematic and bootstraplib

Publish date: 5 June 2020

Theming in Rmarkdown can be hard. You first made some custom CSS or use a provided theme but your figures didn’t change and you have to style your ggplot2 theme. And after it you change your mind (or your boss do) and you need to move this color shade to lighter one. So you change your theme, but forgot to change it in all your CSS and something is going wrong. Same goes for fonts…

Sounds familiar ? Theming is a common problem, because it involves lot of differents elements which aren’t ruled by the same command. Your process look like this.

Thanks to the new thematic package (https://github.com/rstudio/thematic) and the bootstraplib package (https://github.com/rstudio/bootstraplib), you can fastly build themes for your documents without the problems mentioned above.

Style your graph theme with thematic

You can style six differents elements :

You just have to use thematic_on() with your parameters to use it.

library(thematic)
library(ggplot2)
library(tibble)

thematic_on(
  bg = "#F4F4E2",
  fg = "#4c4c4c",
  accent = "#741336",
  font = font_spec("Special Elite", scale = 0.5),
  qualitative = paletteer::paletteer_d("dutchmasters::milkmaid"),
  sequential = sequential_gradient(0.5, 0.75)
)

After that, just make a normal plot like you are used to.

ggplot(tibble(mtcars,
              model = rownames(mtcars)),
       aes(x = model, y = mpg, fill = disp)) +
  geom_col() +
  geom_text(aes(label = disp), 
            position = position_stack(vjust = 1.1)) +
  coord_flip() +
  labs(title = "A barplot with mtcars",
       caption = "Source : mtcars data")

You can add a theme to your graph but will need some further coding. But you need to know that the last element overlap your styling. Because complete themes have fonts and/or colors, they may replace your styling. If you want to keep your theme, you have to set it before to call thematic_on() through a theme_set(theme_minimal()) as an example (see https://github.com/rstudio/thematic/issues/16).

ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width, color =  Species)) +
  geom_point(size = 1.1) +
  geom_smooth() +
  labs(title = "A nice scatterplot for iris",
       caption = "Source : Iris data") +
  theme_minimal(base_family = thematic_get_option("font")$families,
                base_size = thematic_get_option("font")$scale * 11,
                base_line_size = 1.1)

thematic may work with interactive graph packages like plotly or ggiraph if you use some special feature (see https://github.com/rstudio/shiny/pull/2740 and https://github.com/rstudio/thematic/blob/8ed47c589dd4cb611823a958b46f3ed029685bcf/vignettes/Shiny.Rmd#L69)

Use bootstraplib for Rmarkdown theming

It calls Bootstrap and allow you to style directly your document (RMarkdown or Shiny) from R using Sass. You can do a lot with this package. But we will only cover some part of it.

First you need to reference the use of Bootstrap in the YAML header of your Rmd.

---
output:
  html_document:
    bootstrap_version: 4+3
---

After that you can use some functions to style your main elements :

You can also add some hand-made rules with bs_theme_add_variables(). As an example bs_theme_add_variables("font-size-base" = "0.9rem") will style the size of your fonts.

If you want to use Google Fonts, you may need the gfonts package, made by dreamRs (https://github.com/dreamRs/gfonts). It offers simple functions to deal with Google Fonts.

As an example, here is the code chunk which creates the document just below.

# bootstraplib part
library(bootstraplib)
library(gfonts)

# setup and use font
# the setup has to be done once
setup_font("special-elite", "www/")
use_font("special-elite", "www/css/special-elite.css")

bs_theme_fonts(base = "Special Elite")

# font-size
bs_theme_add_variables("font-size-base" = "0.9rem")

# colors
bs_theme_base_colors(bg = "#F4F4E2",
                     fg = "#4c4c4c")

bs_theme_accent_colors(primary = "#741336")

You need to keep in mind two things, when using bootstraplib for R Markdown :

Forging a theme with both packages

If you use thematic after bootstraplib in a Rmarkdown document (it’s also true for Shiny), it will retrieve the styling you passed and use them. That’s a very powerful feature because you will only need to style your document once.

The only thing you need to care about is the font. You have to set it to auto inside thematic_on() to get it nicely.

Here are the corresponding functions between the two packages :

Feature Using thematic Using bootstraplib Using both Additional infos
Background color bg bs_theme_base_colors(bg = ) auto
Foreground color fg bs_theme_base_colors(fg = ) auto
Accent color accent bs_theme_accent_colors(primary = ) auto
Font family font bs_theme_fonts(base = ) font_spec('auto') May need gfonts
Font size font_spec(scale = ) bs_theme_add_variables('font-size-base' = ) font_spec('auto', scale = )
Sequential palette sequential auto Calculated from background, foreground and accent color
Qualitative palette qualitative Manual

As an example, if you use both packages together.

# bootstraplib part
library(bootstraplib)
library(gfonts)
library(thematic)

# setup and use fonts - google fonts
# the setup has to be done once
setup_font("special-elite", "www/")
use_font("special-elite", "www/css/special-elite.css")
bs_theme_fonts(base = "Special Elite")

# font-size
bs_theme_add_variables("font-size-base" = "0.9rem")

# colors
bs_theme_base_colors(bg = "#F4F4E2",
                     fg = "#4c4c4c")

bs_theme_accent_colors(primary = "#741336")

# thematic part
thematic_on(font = font_spec("auto", scale = 0.5))

Conclusion

This two packages don’t do everything but it’s a good step if you don’t want to spend a lot of time styling your RMarkdown document. It could also be a first step to more personalized styling as you can export it.

I really like the “control tower” approach. It doesn’t force you to repeat your styling and makes it really easier to change the style.

Some ressources to go further

To learn more about thematic, the website present a series of good vignettes. You can also have a look at a presentation made by Carson Sievert, one of the package’s author :

If you want to learn more about bootstraplib, I can recommand you the website and the talks of Joe Cheng at the last rstudio::conf.

Acknowledgements

I would like to thank Christophe Dervieux and Romain Lesur for their big help with this articles.