Do it in style

CSS lets you define the style of HTML documents, which is the default output for {xaringan}.

For {xaringan} you’ll typically need two CSS files:

• theme.css to define the style for each broad slide class (e.g. a heading-slide class) and for general things like table design and hyperlink colours
• theme-fonts.css to set the typefaces, which you can define separately for the body text, headers, etc

You reference these files in the YAML header of your {xaringan} R Markdown and the style is enacted when you render it to HTML.

I tweaked the default {xaringan} CSS files to create my own, which you can see in the the GitHub repo.

You can check out the {xaringan} wiki for help and ideas.

.heading-slide {
  background-color: #2372b6;  /* blue background */
  color: #fff;                /* white text*/
  text-shadow: 0 0 0;         /* no text shadow */
  border-bottom: 0;           /* no border */
  font-size: 90px;            /* large text size */
  font-weight: bold;          /* headings are bold */
}

.black { color: #000; }      /* black text for heading slides */
.bold { font-weight: bold; } /* embolden name on title/end slides */

@import url('https://fonts.googleapis.com/css?family=Roboto');
@import url('https://fonts.googleapis.com/css?family=Fira+Mono');

body { font-family: sans-serif, 'Roboto'; }
.remark-code, .remark-inline-code { font-family: 'Fira Mono', monospace; }

Lay down a template

The style is not the only important part of recreating my organisation’s presentations. I also need to create an R Markdown template to demonstrate a restricted set of accepted slide designs. The design philosophy is important to the organisation.

The template itself is just a pre-filled R Markdown that shows the approved slide types and some example content. For example, the first slide of my organisation’s template doesn’t actually contain a ‘title’. Instead it’s an introduction slide that contains the speaker’s name, job, affiliation and Twitter handle.

For example, the user may not know to set class: title-slide and add seal: false in the YAML to override the creation of a default title slide. This is instead pre-specified for the user in the template:

---
output:
  xaringan::moon_reader:
    css: ["default", "gds.css", "gds-fonts.css"]
    seal: false
    lib_dir: libs
    nature:
      highlightStyle: github
      highlightLines: true
      countIncrementalSlides: false
---

class: title-slide, middle

.bold[Firstname Surname]

Job title

Government Digital Service

@username

---

The top half of the code is the YAML that provides metadata for the R Markdown file. Note the reference to the CSS files and seal: false as mentioned.

The bottom half is the pre-filled opening slide with the speaker’s details; the user needs only to modify the filler text. Note the use of the title-slide class and the middle class for vertical alignment. There’s also the .bold[] tag mentioned earlier in this post.

Deliver your package

So how can the CSS and R Markdown template be delivered to people in one bundle? In a package of course.

You need a specific repo structure to provide your template. This is all explained in the Document Templates chapter of the ‘R Markdown: a Definitive Guide’ book by Yihui Xie, JJ Allaire and Garrett Grolemund.

At the very least, your repo will need to contain the path inst/rmarkdown/templates/your-theme/skeleton/, which will typically contain three files:

• theme.css for the slide styles
• theme-fonts.css for the font face specifications
• skeleton.Rmd for the template you created

I’ve also included an img/ folder to hold stock images I’ve used in the template, but this isn’t strictly necessary.

You’ll also need a template.yaml file one level up in inst/rmarkdown/templates/your-theme/. This contains information about the template so users know which one they’re selecting. For example:

name: "Organisation X template"
description: Internal slide style for Organisation X
create_dir: false

A user can now install the package and get access to your styles and template.

Show the thing

You’ve written your code and packaged it, so how do you actually use it?

If hosted on GitHub, like my package, you can install it with:

# install.packages("remotes")
remotes::install_github("matt-dray/gdstheme")

After installation the template will appear in the ‘from template’ section of the new R Markdown window. Selecting it will open the R Markdown template.

The CSS files referenced in the YAML are used to render the style provided when you knit the document.