Fast Rmarkdown Theming with thematic and bootstraplib
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
You can style six differents elements :
bg: the background color, here #F4F4E2 ;
fg: the foreground color, here #4c4c4c ;
accent: the accent color, here #741336. It will also be used to create a sequential palette ;
font: the font you want to use, here Special Elite. You can go further by using
qualitative: the qualitative palette you want to use ;
sequential: the sequential palette, which can be controlled using
sequential_gradient(). By default, it creates a palette from a mix between your background color and your accent color to a mix between your foreground color and your accent color.
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
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)
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 :
bs_theme_base_colors()allows you to set you background (with
bg) and foreground (with
fg) colors ;
bs_theme_accent_colors()for the accent colors ;
bs_theme_fonts()for the fonts.
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 :
The package doesn’t work yet with
pagedownfor the moment, because they are not made with Bootstrap, and strangely with
flexdashboard. However you can use the excellent
xaringanthemerfor your presentation (https://github.com/gadenbuie/xaringanthemer).
You will need to style your table manually. For the moment, only
kableworks well. This comes from the tables packages CSS behavior. The other packages I tested all failed on one part :
gthas the font family only ;
reactablehas the font size, family and color ;
flextablehas the right background color but not the font size/family/color.
Forging a theme with both packages
If you use
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
thematic_on() to get it nicely.
Here are the corresponding functions between the two packages :
||Using both||Additional infos|
||auto||Calculated from background, foreground and accent color|
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))
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.