Chapter 20 Make it fancier

Once you’ve built the basic structure for your R Markdown site, if you’d like to customize it even further, here are a handful of things you can add.

The steps below involve a little bit of HTML and CSS work, but you don’t have to have much experience in these methods to be able to build something cool.

In this section, I’ll walk you through the non-YAML “add ons” to your R Markdown site.

You’ll get the most out of this chapter if you read through the CSS crash course before diving in. You’ll want to be familiar with using the Developer Tools of your web browser and selectors.

20.1 Before you begin

I’m making a few assumptions that by this point you have already updated your R Markdown site with your own content in the Make it yours section and added whatever built-in options you wanted.

For the demo that follows, I’ll keep using the RMD site skeleton with a few additions. I’ve added a few things to the site skeleton, aside from what we’ve walked through in the previous chapters, so that the following examples make more sense. It is okay that your content does not match up exactly with mine.

  • A dropdown menu to the navbar
  • Additional level 1 headers to the home page
  • Turned on a floating table of contents
  • Added github and twitter icons to the navbar
  • We chosen yeti as our theme
    • A note about choosing a theme. To start out, choose a theme whose navbar most closely matches what you’re final vision is. For example, if you want your navbar (and dropdown menus) to be dark with a light colored text, then sticking with Yeti is cool. But if you want a light colored navbar with dark text, sticking with Yeti as the base theme would mean you have a lot more CSS that will need adjusting, and you’re better off using a theme like default as your baseline.

20.2 Anatomy of a fancy R Markdown page

20.3 Adding custom CSS to your site

  1. Make a CSS file, by going to File > New File > Text File.
  2. Save this file in your project directory as style.css.
  3. Add this css: field to your _site.yml.

[commit]

20.4 Aesthetics and branding

Everything that makes your site, look like your site.

  • Google fonts
  • Link color and hover behavior
  • Add a logo
  • Favicon
  • Hero image

20.4.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 _site.yml (and if you’ve been following along, it already is).

20.4.1.1 Select and import your Google font’s script

  1. Go to https://fonts.google.com/ and pick a font for your lesson’s main body text. I’m choosing Muli, but Lato and Source Sans Pro are other nice options.

I 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 20.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, I’m choosing one italic and one bold.

    Choosing additional font weights and styles

    Figure 20.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 20.3: Getting the script to import your Google Font

20.4.1.2 Import the font to your site

  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 within your site but doesn’t use the font 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.

20.4.1.3 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.

[commit]

20.4.3 White space

If you added white space manually before in an earlier section with either
or \, you can remove them because we’re about to add white space in a less manual way.

We’ll take advantage of the fact that we know major sections will be divided by section headers, so we’ll tack on some padding on top of each section header.

We’re adding what seems like a lot of padding–but that’s because our theme by default is going to undo some of this padding with a negative value for the margin-top: property. I know this seems absurd–we won’t get into the details here, but the negative margin is needed so that our headers don’t get hidden behind the navbar when your share links to particular sections of your site.

We’re going to style the title a little differently than the rest of the headers, so we’ll pull it out on its own. It doesn’t need as much space as the other headers do.

[commit]

We’ll also add more white space in between the TOC and the rest of the body content, but we do this only when we have the space to— in other words, when our user’s screen is large enough.

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:

[commit]

20.4.6 Add a favicon

You know the little tiny icon that gets placed in the corner of your browser tabs or gets placed in the bookmark’s bar? That’s a favicon!

To add a favicon you need:

  1. An HTML file with one line of code
  2. An image to use as your favicon
  3. To edit _site.yml so you can reference the HTML file.

20.4.6.1 Choose your favicon image

  1. Choose an image–don’t have one? You can make one with a favicon generator. I chose the emoji graduation cap.
  2. Save the image you’d like to use as (use a PNG or ICO file) and place it in your project directory (for the best results, use a square or circular image).

20.4.6.2 Embed the favicon in an HTML file

  1. Make a new HTML file by clicking File > New File > Text File.

  2. Insert the following, replacing favicon.ico with your image filename.

  3. Save this file as header.html. You can choose a different name.

20.4.6.3 Reference the HTML file in _site.yml

We want this HTML file to go in the <head> tag of our site. The head tag is like the Font Desk/ admin of our site–and its the place where the favicon will be taken care of.

  1. Open _site.yml.

  2. Under the html_document: section, insert the includes: and in_header options like so:

If you already have a file that you’ve included with the in_header field, then you can open up that file, and add the favicon line of code at the top of your existing file, OR you can list both header files separately, by listing them within brackets like this: [header.html, <other-file.html>,]. The order you list them in is the order that the browser will use them (which is only really important to know so that if you need to troubleshoot, you can try swapping the order).

[commit]

20.4.7 Add a hero image

To add the big image at the top of page (a.k.a hero image), we need to make an HTML file containing our image and text.
Let’s add one to only our homepage.

We’ll need:

  • An HTML file
  • To edit the YAML of our index.Rmd
  • A image to use as our hero image
  • CSS
  • To adjust the table of contents positioning
  • Aspirational step: to tweak for mobile

How to do it:

20.4.7.1 Make an HTML file

  1. Go to File > New File > Text File.

  2. Copy and paste the HTML code below into this file (see Figure 20.4 to decode this!)

  3. Replace “DATA 101” with the text that you’d like to see on the top line.
  4. Replace “DATA SCIENCE” with whatever text you’d like to see on the bottom line.

  5. Close and Save this file in your project directory as hero-image.html. The name of the file does not have to be hero-image.

Here’s what each of the lines in hero-image.html is doing:

Decoding the hero-image.html file

Figure 20.4: Decoding the hero-image.html file

20.4.7.2 Have R Markdown apply the HTML file

  1. Open index.Rmd.
  2. Reference the HTML file in index.Rmd’s YAML with the includes: and in_header: lines.

This will add the image to ONLY the index.Rmd page of your site, which is appropriate since the index will serve as the homepage. We could have instead added in_header: to our _site.yml to apply the image to EVERY site page (but consider whether this might be visually overwhelming for your site!).

When you add an in_header: option to a single page’s YAML, it will override the more “global” in_header: option set in _site.yml. So if you still want the global in_header: to apply (e.g. the header.html file that we used for our favicon), then you’ll need to list both files in the single page’s YAML. Like this, for example our index.Rmd YAML now looks like this:

:::tip Including an image like this in the header of the page is kind of a hack (the

tag is supposed to be reserved for admin/ meta stuff of the website only, not really content or images)– so in order for this to work properly if you have two HTML files listed, make sure the hero-image.html is listed last. :::


Ooh la la: Try out a completely blank index.Rmd with nothing but the YAML with a header image for a visually-striking homepage.

20.4.7.3 Choose your hero image

  1. Find the hero image that you’d like to use. It should be something that will still look good even on a variety of different screen sizes. So, patterns usually work. Or landscapes. If you need some ideas, check here. In the rstudio4edu template, I also drop in a couple hero image files you can use–including one with a transparent background (a .png, not .jpeg file) so that (in a bit) you can manipulate the background color of it in the CSS.

  2. Save this image in your project directory.

20.4.7.4 Styling the hero image

You could style this endlessly, but here’s the CSS we’re using. Each selector corresponds to the class names we used in hero-image.html:

  1. Open style.css
  2. Paste the three style rules below into your css file.
  3. In the hero image selector, find the background-image: property. Replace file within the url parentheses url() with the path of the image that you’d like to use.

Find the part of the background-image: property that uses a linear gradient. This is a trick that will add a translucent dark overlay on your image so that your text on top will be easier to read (0 is completely transparent, 1 is completely opaque). If the hero image you chose is already dark enough, then you may not need the overlay, and you can either delete linear-gradient( rgba(0,0,0,.2), rgba(0,0,0,.2) ) or change the last numbers to 0.

Why use a background color? Yes, we did specify a background color and a background image for our .hero-image selector on purpose. Two reasons: (1) If your site ever has trouble loading your image, the background color is a nice stand-in. (2) If you use one of our template hero-images that was created as a pattern on a transparent background (hero-transparent.png – or any hero image that has a transparent background), then the background color you specify in your CSS will be the background color you see. Makes it easy to customize!

  1. Build your site and make sure that you like how your hero image looks. Notice that you can choose NOT to show a hero image, or either of the text lines by specifying display: none in the CSS.

[commit]

If you don’t like how your hero image is positioned in the container, you can mess around with the background-position property. Right now we use the keyword “center” to specify its x and y position–but other keywords you can use include: top, bottom, right, and left. You can also set the background position to be a length or a percentage of the container width.

We haven’t changed the font for the text that overlays the hero image in this example, but you could always apply a Google Font that you’ve already imported by adding the CSS property font-family: to the CSS style rules for the .top-text and .bottom-text selectors.

20.4.7.5 Adjust TOC positioning

Adding a hero image in this way makes our floating table of contents do strange things. We’ll need to fix this with the following CSS:

/*-----------------TOC----------------*/

/* Makes TOC sticky (needed if you used a hero image) */

.row-fluid{
  display: flex; /* Necessary for sticky TOC*/

}

.tocify {
  position: -webkit-sticky;
  position: sticky; 
  top: 120px; /*Controls where TOC stops when sticky */
  width: 100% !important;
}

[commit]

20.4.7.6 Tweak for mobile

But on mobile and other small screens, we don’t want the floating TOC to be there. And we’d probably like to make the overlaid text to either not be displayed (display: none) or just make the text smaller (which is what I’ll demo with the CSS below). Let’s try it. We’ll need to use a media query again:

The style rules below will only apply for screens that are 767px or smaller:

20.5 Table of contents

We’ve already started changing TOC styles after having added a hero image. Now we focus on the TOC aesthetics.

First we will get rid of the TOC border

  1. Find the .tocify selector that we added earlier when we were working on the hero image.

  2. Add border: none; as a new line in this style rule.

<img src="images/screenshots/doc-toc-no-border.png" width="50%" style="display: block; margin: auto;" />

Next we’ll style the links that make up the TOC.

  1. Let’s change the color of the links slightly and also increase the font size

  2. Change the color and background color of active links, the link that show which section you are actively viewing:

  3. Finally, change what happens when you hover over the regular and active links:

<img src="images/screenshots/doc-toc-links.png" width="50%" style="display: block; margin: auto;" />

[commit]

20.7 Questions counter

Finally, if you plan on using questions for learners in your site (for example, for labs or homework sets), you might want to make it easier to call out these questions by styling them. Like this:

This idea and CSS was inspired by Maria Tackett’s STA210 course: https://github.com/STA210-Sp19/website

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

</div>`

##Footer

Let’s also add a footer. You need to:

  1. Make a new HTML file and insert your footer content 1.5) If you’re going to include images in your footer content (like logos or icons), then add those to your project directory.
  2. Add it to your _site.yml with the includes: after_body:
  3. Style the footer elements using CSS

Here’s how we do this:

  1. Create your HTML file.
  2. Save it in your project directory. Name it footer.html. You can choose a different name.
  3. Paste something like this in the file:
  1. I suggest you use the footer to include mention of licensing [say more about this]. It’s a good place to add another

    tag with this content, for example:


<div class="footer"> 
  
  <hr> 
  
  <p> This content is licensed under the CC-BY license. </p>

  <p class="rstudio4edu-footer">This site was created with an <a class="rstudio4edu-link" href="https://rstudio4edu.github.io/rstudio4edu-book/"> <img class="rstudio4edu-footer-logo" src="logo-mark-rstudio4edu.png">&nbsp;rstudio4edu</a> template.</p>


</div>

What does this do?

  • The
    is going to be a little section divider line.
  • the div tag with class “footer” is going to be the container that we’ll use to style most of our footer contents later in the CSS.
  • Within the div tag, you can put your chunks of footer text inside

    tags (for “paragraph”).

  • In the example above, we’ve added the rstudio4edu icon and made it linked, so that’s what the tags and tags are for.

Here’s the CSS we’ll use to style each of the part of our footer:

20.8 Add multiple CSS files

Note that you can have several CSS files, if for example you have one for your organization and another custom file. I’m not going to do that, but just want to let you know that this is an option.

20.9 Recap

So here are all the ways that we made our site fancy:

  • Added Google Fonts
  • Customized our links
  • Added white space around headers and site sections
  • Added a logo
  • Added a favicon
  • Added a hero image with overlaying text
  • Styled the Table of Contents links
  • Customized the navbar
  • Created specially-styled questions
  • Created a footer
All illustrations CC-BY-NC : You can download them by clicking here
All other materials CC-BY unless noted otherwise.