Bootstrap cards in distill

How to enable bootstrap 4 on a distill website, even though you probably don’t need to. I like it though because I get to add pretty bootstrap cards

true
2021-04-19

When creating R markdown websites, I often find myself wanting to organise content into a nice-looking grid of links. For example, in a recent project I wanted to be able to create something like this:

Starting R markdown

An introduction to R markdown. The target audience is a novice R user with no previous experience with markdown.

Starting ggplot2

An introduction to ggplot2. The target audience is a novice user with no previous experience with R or ggplot2.

Starting programming

This is primarily a tutorial on making generative art in R, but in doing so introduces core programming constructs and data structures. It is assumed the user has some previous experience with ggplot2.

It bothered me that this wasn’t as straightforward as I was expecting, so for one of my side projects I’ve been putting together a small package called bs4cards to make this a little easier inside an R markdown document or website. There are some introductory articles posted on the bs4cards package website showing how the package works, and there’s no need to duplicate that content here. However, because this website uses the distill package (Allaire et al. 2021) and the package website is built using pkgdown (Wickham, Hesselberth, and Salmon 2021), it seems like a good idea to have at least one post on both sites that uses bs4cards.

Enabling bootstrap 4

The reason for doing this is that the first step in using the package is to make sure that your R markdown document uses version 4 of bootstrap: the bs4cards package takes its name from the cards system introduced in bootstrap version 4, and will not work properly if used in R markdown documents that rely on bootstrap version 3, or don’t use bootstrap at all. To ensure that you are using bootstrap 4, you need to edit the YAML header for your document to specify which version of bootstrap you want to use. The instructions are slightly different depending on what kind of document you’re creating:

Vanilla R markdown

For a plain R markdown document or website (i.e., one where the output format is html_document) here is the relevant section of YAML you might use:

output:
  html_document:
    theme:
      version: 4

This overrides the R markdown defaults (Xie, Dervieux, and Riederer 2020) to ensure that the output is built using bootstrap 4.5.

Pkgdown

To enable bootstrap 4 in a pkgdown site, the process is similar but not identical. Edit the _pkgdown.yml file to include the following

template:
  bootstrap: 4

Note that this relies on a currently-in-development feature, so you may need to update to the development version of pkgdown to make this work.

Distill

Distill R markdown does not use bootstrap, which is a little inconvenient if you want to use bs4cards with distill. With a little effort it is possible to enable the entire bootstrap library in a distill site, but this can lead to undesirable side-effects because bootstrap has a lot of styling that doesn’t look visually appealing when mixed with the istill styling. The solution I’ve adopted for this is to use a custom bootstrap build that includes a minimal number of bootstrap components. If you want to try the same approach, you can download the strapless.css file to the same folder as the distill post you want to enable it for, and include the following YAML in the post header:

output:
  distill::distill_article:
    css: "strapless.css"

If you want to enable strapless for the entire site, this markup goes in the _site.yml file and the css file should go in the home folder for the project. Once that’s done you should be ready to go. That being said, you’d be wise to be careful when adopting this approach: the strapless build is a crude hack, and I haven’t tested it very thoroughly.

Testing with pretty pictures

Just to make certain, let’s check that it does what we want by generating cards using the galleries data that comes bundled with the bs4cards package:

library(bs4cards)
galleries %>% 
  cards(title = long_name, image = image_url)
Ash Cloud and Blood
Ghosts on Marble Paper
Ice Floes
Native Flora
Silhouettes
Track Marks
Viewports


Looks about right to me?

Last updated

2021-09-17 17:03:00 AEST

Details

source code, R environment

Allaire, JJ, Rich Iannone, Alison Presmanes Hill, and Yihui Xie. 2021. Distill: ’R Markdown’ Format for Scientific and Technical Writing. https://CRAN.R-project.org/package=distill.
Wickham, Hadley, Jay Hesselberth, and Maëlle Salmon. 2021. Pkgdown: Make Static HTML Documentation for a Package.
Xie, Yihui, Christophe Dervieux, and Emily Riederer. 2020. R Markdown Cookbook. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook.

References

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/djnavarro/distill-blog, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

Navarro (2021, April 19). Notes from a data witch: Bootstrap cards in distill. Retrieved from https://blog.djnavarro.net/bs4cards-in-distill

BibTeX citation

@misc{navarro2021bootstrap,
  author = {Navarro, Danielle},
  title = {Notes from a data witch: Bootstrap cards in distill},
  url = {https://blog.djnavarro.net/bs4cards-in-distill},
  year = {2021}
}