---
title: "7. Customizing Quarto Documents with SCSS"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{7. Customizing Quarto Documents with SCSS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
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:

````yaml
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](https://www.w3schools.com/css/css_colors_hex.asp). You can also set fonts. To learn more about setting fonts, look [here](https://www.w3schools.com/css/css_font.asp). To learn more about all of this, watch this [YouTube video](https://youtu.be/qw1OqIhr8EU?si=UPms-SDynvgalpSL).

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.

```css
/*-- 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:

````r
rUM::write_scss("styles")
````

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

````yaml
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](https://quarto.org/docs/output-formats/html-themes.html#customizing-themes).