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:
An introduction to R markdown. The target audience is a novice R user with no previous experience with markdown.
An introduction to ggplot2. The target audience is a novice user with no previous experience with R or ggplot2.
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.
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:
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: 4This overrides the R markdown defaults (Xie, Dervieux, and Riederer 2020) to ensure that the output is built using bootstrap 4.5.
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: 4Note 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 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.
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)
Looks about right to me?
2023-05-27 18:28:18.962217
@online{navarro2021,
author = {Navarro, Danielle},
title = {Bootstrap Cards in Distill},
date = {2021-04-19},
url = {https://blog.djnavarro.net/bs4cards-in-distill},
langid = {en}
}