In RaymondBalise/rUM: R Templates from the University of Miami

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

Customizing the appearance of your Quarto documents doesn't have to be complicated. The write_scss() function simplifies the process of creating a SCSS template file and managing SCSS style sheets, making it easier to achieve the exact look you want for your documents.

Getting Started

When you create a new Quarto project with rUM::make_project(), it creates a file called analysis.qmd. At the top, you will see YAML code like this:

format:
  html:
    embed-resources: true
    theme:
      - default
      - custom.scss

The lines with theme, default, and custom.scs control the appearance of the document. The default custom.scss provides a foundation for styling to change the appearance of the document. You can change colors, fonts, and spacing. Let's explore how to do this.

What Does custom.scss Contain?

It is a text file that has 3 sections: SCSS defaults, mixins, and rules. The defaults controls the appearance of named parts of your document. For example, the font color of the page is set by the $primary: option. That variable contains a hex color code or a quoted color name. To learn more about hex colors, look here. You can also set fonts. To learn more about setting fonts, look here. To learn more about all of this, watch this YouTube video.

It is important to note that SCSS uses double forward slashes (//) to indicate comments like R would use #. If you want to set an option, remove the two slashes.

/*-- scss:defaults --*/
// Colors
// $primary: #2c365e;  
// $body-bg: #fefefe;
// $link-color: $primary;
// Fonts
// $font-family-sans-serif: "Open Sans", sans-serif;
// $font-family-monospace: "Source Code Pro", monospace;


/*-- scss:mixins --*/
// This is empty by default -- add your mixins here


/*-- scss:rules --*/
// Custom theme rules
// .title-block {{
//   margin-bottom: 2rem;
//   border-bottom: 3px solid $primary;
// }}
//
// code {{
//   color: darken($primary, 10%);
//   padding: 0.2em 0.4em;
//   border-radius: 3px;
// }}

Customizing Styles

Let's modify the styles sheet to change the background color to a light gray. Open styles.scss and modify the background color variable by removing the SCSS comment (//) and altering the hex code value for $body-bg:

/*-- scss:defaults --*/
// Colors
$body-bg: #f5f5f5;    // Light gray background

Creating Additional Style Sheets

Usually, you will only need to use one styles sheet. However, if you want to add a new style sheet called "styles.scss". Run this code in the console:

rUM::write_scss("styles")

After running this command, rUM will try to automatically update your YAML to be:

format:
  html:
    embed-resources: true
    theme:
      - default
      - custom.scss
      - styles.scss

Handling Different YAML Structures

Sometimes you might encounter or create a Quarto document with a different YAML structure than we provide with rUM. This can happen if your company or organization has its own style sheet. In these cases, write_scss() provides helpful guidance. For example, if the function doesn't find the expected YAML structure, you'll see this console message:

Be sure to update your listed SCSS files in the YAML manually:
format:
  html:
    embed-resources: true
    theme:
      - default
      - custom.scss
      - your_organizations_style.scss       # Add this line

This ensures you can still proceed with your customization, even if your YAML structure differs from the default.

Why Use Multiple Style Sheets?

Using multiple SCSS files can be advantageous when:

• Organizing different aspects of your styling (font, colors, layout)

• Maintaining separate themes for different purposes

• Collaborating with others who need to modify specific style elements

• Testing different style combinations without modifying your base styles

Conclusion

The write_scss() function makes it straightforward to expand your Quarto document's styling capabilities while maintaining a clean, organized structure. Whether you're making simple color changes or developing complex themes, this tool helps you focus on creativity rather than file management.

For more advanced SCSS customization options, visit the Quarto documentation on HTML themes.

RaymondBalise/rUM documentation built on April 14, 2025, 11:48 a.m.