Customizing Quarto with froggeR

Understanding SCSS Structure

The write_scss() function creates a template with three main sections:

1. Defaults (/*-- scss:defaults --*/)
   • Basic styling variables
   • Color schemes
   • Font settings
2. Mixins (/*-- scss:mixins --*/)
   • Reusable style patterns
   • Custom style functions
3. Rules (/*-- scss:rules --*/)
   • Specific element styling
   • Custom classes
   • Layout adjustments

Working with Comments

The SCSS template uses // for commented styles. These act like a menu of styling options:

/*-- scss:defaults --*/
// $primary: #2c365e;          // Main theme color
// $body-bg: #fefefe;          // Background color
// $link-color: $primary;        // Inherit from primary

To activate any style:

1. Remove the // at the start of the line
2. Save the file
3. Re-render your document

Working with Multiple SCSS Files

To multiple or a organization-specific SCSS file in your Quarto document, update the YAML header. Be advised that modifying the document-level YAML (i.e., the YAML for the .qmd file) will override any options set in _quarto.yml & _variables.yml.

---
title: "My Document"
format:
  html:
    theme:
      - default
      - custom.scss        # Added during project 
      - your-other.scss    # The new one you're adding
---

Note: Order matters! Any style(s) set in custom.scss override Quarto’s defaults, and your-other.scss overrides the previous two. If your document isn’t rendering as you believe it should, check the files. If you have a border style set in custom.scss but the output file isn’t correct, there’s a good possibility that there’s something set in your-other.scss causing conflicts. Resolve the issue and re-render. :)

Basic Customization Examples

Link Color

Here’s an example of changing the default link color from the assigned $primary color (blue) to dark green.

Link color styling - Before

/*-- scss:defaults --*/
// These lines are inactive (commented out):
// $link-color: $primary;

Remove the // to activate and change $primary to #1e6909:

$link-color: #1e69090;

Link color styling - After

/*-- scss:defaults --*/
$primary: #1a936f;      // Forest green
$body-bg: #f8f9fa;      // Light gray

Advanced Customization

Combine multiple elements for sophisticated styling:

/*-- scss:defaults --*/
// First, set your variables
$primary: #2c365e;
$font-family-monospace: "Fira Code", monospace;

/*-- scss:rules --*/
// Then create custom rules
.title-block {
  margin-bottom: 2rem;
  border-bottom: 3px solid $primary;
  
  h1 {
    color: darken($primary, 10%);
    font-weight: 600;
  }
}

// Style code elements
code {
  color: lighten($primary, 10%);
  padding: 0.2em 0.4em;
  border-radius: 3px;
}

Modern Document Headers

/*-- scss:rules --*/
.title-block {
  background: linear-gradient(to right, $primary, lighten($primary, 20%));
  padding: 2rem;
  margin-bottom: 3rem;
  color: white;
  border-radius: 5px;
}

Enhanced Code Blocks

/*-- scss:defaults --*/
$code-block-bg: #f8f9fa;
$font-family-monospace: "Fira Code", monospace;

/*-- scss:rules --*/
pre {
  border-radius: 4px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  margin: 1.5em 0;
}

Professional Links

/*-- scss:rules --*/
a:not(.nav-link) {
  border-bottom: 1px dotted $primary;
  text-decoration: none;
  transition: all 0.2s ease;
  
  &:hover {
    border-bottom: 1px solid $primary;
    background-color: rgba($primary, 0.1);
  }
}

Settings Issues

1. Variables Not Updating
   • Restart R session after config.yml changes
   • Check _variables.yml exists in project
   • Verify YAML structure in documents
2. Multiple Projects
   • Settings apply to new projects only
   • Existing projects keep their settings
   • Update _variables.yml manually if needed