Chapter 10 Make it fancier

10.1 Extra packages




10.2 Use bootswatch CSS


10.3 include or not?

Now it’s time to customize our single lesson even further. We can do a little bit of HTML and CSS work to add-on some fancy features.

10.4 Before you begin

If you’re starting here, I assume that by this point you have already:

  • Updated your single lesson with your own content in the Make it yours section. (For my demo that follows, I’ll keep going with the boilerplate content since at this point everyone will have different content anyhow).

  • At a minimum, added a few elements from the Dress it up section, specifically:
    • A theme (I’ve chosen flatly)
    • A floating table of contents
    • Code highlighting (I chose tango)

So that you know where I’m starting, here’s what my YAML frontmatter looks like right now:

If this is your first time having a go at CSS, then you might want to check out the CSS crash course so that you have a sense for how/why we’re doing what we’re doing—otherwise, buckle in for the ride!

10.5 Include a css file

If you want to add any custom styling to your doc, the first thing you’ll need to do is to create a CSS file in your project directory and then tell R Markdown that it exists.

  1. Go to File > New File > Text File
  2. Save this file as style.css in your project directory. May as well keep this file open because we’re about to add a bunch of stuff to it!
  3. Open the .Rmd file you’re working on.
  4. In the YAML, reference the new CSS file by adding the css: option followed by its filepath.

  5. Save your changes.

Now you’re all set to start CSS-ing!

10.6 Branding and aesthetics

We’ll start by making changes related to the look and feel of your doc.

10.6.1 Google Fonts

To change the appearance of your text with a new font, you need to:

  • Pick a Google font
  • Add it to your CSS file
  • Style specific text using CSS selectors
  • Make sure your CSS file is linked in your YAML (and if you’ve been following along with us, it already is). Select and import your Google font’s script

  1. Go to and pick a font for your lesson’s main body text. We’ll choose Muli, but Lato and Source Sans Pro are other nice options.

We recommend going with sans-serif fonts (i.e. no little feet on the letters) for the main text because they’re easier to read at smaller sizes on screens compared to serif fonts. Don’t pick anything too narrow, too wide, or ornate.)

  1. Select the font you want by clicking on the upper red + sign, and navigate to the small pop up window.

    Selecting a Google font

    Figure 10.1: Selecting a Google font

  1. Click on the CUSTOMIZE tab, and select the extra font weights and styles you want. Don’t check any that you don’t think you’ll use (because it slows down your lesson’s loading time ever-so-slightly when you add more). In addition to regular, we’re choosing one italic and one bold.

    Choosing additional font weights and styles

    Figure 10.2: Choosing additional font weights and styles

  1. Now click on EMBED and look under the @IMPORT tab. Copy the code within the <style> tags (you don’t need the style tags themselves). We will also need the second code chunk in a couple steps that says Specify in CSS, so keep this page open to come back to that.

    Getting the script to import your Google Font

    Figure 10.3: Getting the script to import your Google Font Import the font to your lesson

  1. Back in the RStudio IDE, open up your style.css file.
  2. On the very first line, paste in the Google Font import code for the Muli font. This makes the font available–but doesn’t actually use it yet.

You might see others import Google fonts by embedding the script (with <script> tags) in an HTML file instead. This is perfectly legitimate. But if you’re just starting out, it’s easier to keep all the font stuff together in a CSS file, which is why we’re doing it this way. Apply the font to your text

We have our font imported, but now we have to be explicit with R Markdown about where to apply it. Let’s create our first CSS style rule below. We will apply the Muli font to our body’s text by using the font-family: property.

  1. Copy and paste the following style rule to style.css beneath the other line of CSS we’ve already added.
  2. Let’s also specify the font size to be 19px by adding the font-size: property.

  3. Make sure that each line within {} ends with a ;.

Keep tidy! Organize your CSS using comments like /* --insert-comment-- */ to create make-shift section dividers for your CSS, as we’ve done above. We’ll be adding many style rules, and we’ll want some way to keep track of everything as our CSS file grows.

  1. Time to admire your handiwork and decide whether or not you like it. You can repeat the steps above to apply different fonts to different parts of your lesson. For example, you could create another style rule using .title instead of body to apply a different font to the Title of your lesson.

Remember that in order for any of your CSS to take effect, your style.css file has to first be referenced in your YAML.

10.6.4 White Space

If you added white space manually in the 6.5 section, you can remove that now, and we’ll add some in programatically with our CSS.

  1. First up is adding space above and below the title with the the margin-top: and margin-bottom: properties.
    • The unit em here is equal to whatever you have your font-size set to. This is nice because it means your white space will scale even if you change your font size.
  2. But this leaves our logo squished up at the top of our page–so let’s adjust our earlier style rule that we used for our logo, by increase the logo’s top margin to 2.75em also. When a margin has four numbers, the first value applies to the top.

  3. Let’s add white space in between our other headers. We want there to be a little more white space above our highest level headers (h1) than above our headers lower in the hierarchy (so that sections are more clearly delineated), so we’ll style the h1 headers separately from the other headers.

    • The selector .section h1, .section h2, etc. selects only headers within a section (in other words, this excludes the title and subtitle, which are also technically h1 and h2 headers–but which don’t exist inside the “section” content of the page.)
  4. We added white space in between our headers, but we can also add space in between the TOC and the body content, which right now is so squished together. Let’s increase the space–but only when the screen is wide enough to allow it. For this, we’ll have to use our first media-query.

    • A media query is like an additional outer rule that says, “hey, only apply the CSS rule inside if [insert condition about screen width here] is met”. Media queries are useful for styling something different on a big screen than you would on mobile, etc.

    • In the case below, we only increase the space between the TOC and the body content if your user’s browser screen is at least 992px wide:

  1. Lastly, you may have noticed that there’s a lot of excess empty white space at the end of the lesson, which can lead to a lot of unnecessary scrolling. Let’s get rid of ost of that space with this addition to our CSS:

10.7 Table of contents (TOC)

Now it’s time to style the table of contents. Right now my demo .Rmd only has two section headers, so I’ll add two more headers so that it’s easier to demonstrate the changes I’m making to the TOC. Here’s where I’m starting:

  1. First we will get rid of the TOC border and make the font size a little smaller:

  2. Next, we increase the space between each of the TOC items with the line-height: property, for some gratuitous breathing room.
  3. We also add a solid grey line as a border, as a subtle divider between the TOC and the rest of the page.

  4. Now we remove the dark-blue background for the TOC links that you see when a link is active or when you hover over it. We do this using the background-color: property and setting it to white with #ffffff.
  5. We also change the color of the active and hovered links to be a little lighter (#787878) than the base color.

10.8 Questions counter

Finally, if you plan on using questions for learners in your doc (for example, for homework problems), you might want to make it easier to see these questions by styling them. Like this:

This idea and CSS was inspired by Maria Tackett’s STA210 course:

The CSS you need is this–it’s a lot, but for most use-cases the only style rule you really need to worry about editing is the second-to-last one, with the content: and color: properties:

  • If you want to change the styling to say something other than “Question”, then you modify content: "Question ".
  • You can change the color of the called out question, too, with the color: #5ebccf;

How to use the question counter:

In your .Rmd, you have to enclose your numbered list items that you want to be styled questions with special div tags:

<div class="question">` 

1. My first question 
1. My second question