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
04-19-2021

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 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’s an introductory vignette 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 natively use bootstrap, but you can enable it by including the relevant information through the header. This is a two step process. First, create a file called header_bs4.html or something. The content of the file should be as follows:

<!-- bootstrap 4, for non-distill content -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/css/bootstrap.min.css" integrity="sha384-B0vP5xmATw1+K9KRQjQERJvTumQW0nPEzvF6L/Z6nronJ3oUOFUFpCjEUQouq2+l" crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.6.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-Piv4xVNRyMGpqkS2by6br4gNJ7DXjqk09RmUpJ8jgGtD7zP9yug3goQfGII0yAns" crossorigin="anonymous"></script>

Then you need to add the following lines to your YAML header:

output:
  distill::distill_article:
    includes:
      in_header: header_bs4.html

If, like me, you only want to enable bootstrap 4 for a specific post, this goes in the YAML header for that post only, and the header_bs4.html file goes in the same folder as the .Rmd file for your post. Alternatively, if you want to enable bootstrap 4 for the entire site, this markup goes in the _site.yml file, and the header_bs4.html file goes in the same folder as _site.yml.

Once that’s done you should be ready to go!1

Testing with kittens

Just to make certain, let’s check that it does what we want by generating a random card using kitten images and lorem ipsum placeholder text:

bs4cards::sample_card()
A kitten card

Haec para/doca illi, nos admirabilia dicamus. Nosti, credo, illud: Nemo pius est, qui pietatem-; Vos autem cum perspicuis dubia debeatis illustrare, dubiis perspicua conamini tollere.


Looks about right to me?

Last updated

2021-04-19 11:34:12 AEST

Details

source code, session info, lockfile

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.


  1. Well, sort of. This approach enables all bootstrap formatting through the whole document, and this does have an impact on how a few other things (e.g., links) are displayed. This footnote is my note-to-self reminding me to fix this issue!↩︎

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}
}