Customizing a Website

Tip Learning Objectives

By the end of this module, you will be able to:

  • Identify components of SCSS stylesheets
  • Describe key code syntax differences between SCSS and R code
  • Use SCSS stylesheets to customize a deployed Quarto website

SCSS Background

Technically, when we render a Quarto project we are asking Quarto to convert the .qmd file into .html and apply a CSS (Cascading Style Sheets) stylesheet. This is why your deployed website up to this point has had a blue navbar, a white background, and black text (to name a few theme elements governed by the implied CSS stylesheet).

Quarto supports us making our own, customized stylesheets with Sass (Syntactically Awesome Stylesheet) to tailor the look and feel of our website to exactly our personal preference. The relevant file type is .scss (Sassy CSS; still pronounced “sass”). These files can be written in a combination of CSS and Sass so the syntax might look a little alien to you but this workshop will try to provide a useful level of practical detail for you to engage with these stylesheets even if this is your first foray into that world.

NoteR Versus SCSS Comparison

If you’re an R coder, it might be helpful to compare how R assigns values to objects versus how SCSS binds values to variables as well as how to write a comment (i.e., a non-coding line).

R code

# Comment
object <- value

Sass code

// Comment
$object: value;

Customize the Website with Sass

1. Create Sass Stylesheets

Create two new files: “theme_light.scss” and “theme_dark.scss”. This will let us easily create a light mode and a dark mode for our website so that visitors can click a toggle in the navbar to choose their desired aesthetic.

Once you have these files, click the collapsed menu below and copy/paste all of its contents into both empty SCSS files.

SCSS Contents 
/*-- scss:defaults --*/

// Colors
/* Found on https://coolors.co/palettes/trending */
$org-1: #ff9f1c;
$org-2: #ffbf69;
$mint-1: #2ec4b6;
$mint-2: #cbf3f0;
$url-blue: #4361ee;

/* generally useful other colors */
$cream: #F4F3EE;
$charcoal: #191919;
$gray-1: #8A817C;
$gray-2: #BCB8B1;
$gray-3: #d6d6d6;

// Fonts
$font-size: 25px;
@import url('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap');

// Base document colors
$navbar-bg: $org-1; // navbar
$navbar-fg: $charcoal; // navbar foreground elements
$navbar-hl: $org-2; // highlight color when hovering on a page
$sidebar-bg: $org-2; // sidebar
$sidebar-fg: $charcoal; // sidebar foreground elements
$body-bg: $cream; // page background
$body-color: $charcoal; // page text
$footer-bg: $mint-1; // footer
$footer-fg: $charcoal; // footer text
$link-color: $url-blue; // hyperlinks

// Code text
$code-bg: $gray-2; // inline code background color
$code-color: $charcoal; // inline code text color
$code-block-bg: $gray-2; // code block background color

/*-- scss:rules --*/

// Underline URLs
.reveal .slide a { text-decoration: underline; }

// Improve background contrast for code chunk ouput
pre code:not(.sourceCode) { background-color: $gray-2; }

This will result in your light and dark mode being identical to start with but that’s okay because this method makes sure that the format of both SCSS files is correct.

2. Integrate Into the Website

To get your website to use these .scss files, we’ll need to make some minor edits to the website’s YAML. **Open your “_quarto.yml” file in your IDE and add the following lines**.

WarningPaste in the Right Place!

Note that the below code chunk includes a html: element but your existing _quarto.yml will already have that element! That bit is included below so you know where to copy/paste the new lines into your existing YAML.

If you’re using a mostly unmodified _quarto.yml, this will be about 4 lines up from the very bottom.

  html:
    theme:
      light: theme_light.scss
      dark: theme_dark.scss
    mainfont: Open Sans

Double check that your indentation is right after you copy/paste those lines! theme: and mainfont should both be one indent more than html: while light: and dark: should have an additional indent beyond theme:.

3. Customize to Your Taste

The Sass code you copy/pasted is functional and inoffensive but likely does not reflect your personal aesthetic sensibilities. So, take some time to find some colors that you prefer. This is also a great time to make your dark mode actually a dark mode (currently it has the same content as the light mode .scss file).

First, I’d recommend visiting coolors.co and looking at their trending color palettes for one that feels like your vibe. To incorporate that in your site you’ll need to copy the hexadecimal code (6-digit color code) and add it to the relevant .scss file.

Typically the simplest way to do this is to assign each color to a variable name, just like the default colors you copy/pasted in earlier (e.g., $cream: #F4F3EE;). Be sure that each line starts with a $ and ends with a ;.

Once you’ve assigned variable names to your new color(s), update the existing fields in the lower half of the .scss file with those variable names. Consult the comments for some explanation of what those variable names are called. Remember too that each variable name needs to start with $ when you invoke it (so that Sass knows you’re talking about an existing variable).

To find new possible fonts, check out Google Fonts (fonts.google.com) and search around for one that seems like a good fit for your personal style. When you have identified a font that you like, follow these instructions:

  1. Click on the font to go to its homepage
  2. Click the blue “Get font” button in the top right corner of the page
  3. Click the blue “ Get embed code” button
  4. Click the @import radiobutton in the top of the resulting sidebar
  5. In the first code chunk, copy everything between the two <style> HTML tags
  6. In your .scss files, paste the copied text somewhere near the font that is already there to begin with
  7. Finally, update the mainfont: element of _quarto.yml with the new font name

4. Test it Locally

To make sure that your new website displays correctly, run quarto preview. If it doesn’t, edit the offending file(s), save those edits, and look at the preview again.

This step can be especially critical when fiddling with (yes, that’s the technical term ) colors for your website. Use the preview extensively to be sure you’re happy with your chosen color palette.

5. Render & Push

Once you’re happy with how the preview looks:

  1. Run quarto render
  2. Commit & push/sync all the files that you changed
  3. Wait for the GHA to complete

Activity - Try it Out

NoteYour Turn!

Let’s take a bit for you to customize your Sass stylesheets!

Additional Information