Customizing Quarto with froggeR

Introduction 🐸

One of froggeR’s core strengths is its ability to maintain consistent settings and styling across multiple projects. This vignette demonstrates how to set up and customize your Quarto documents using froggeR’s powerful configuration system.

---

Setting Up Reusable Options

Initial Configuration

The froggeR_settings() function manages your document settings through an interactive interface. This is typically a one-time setup that benefits all future projects:

froggeR::froggeR_settings()

This creates a configuration file at ~/.config/froggeR/config.yml that persists across R sessions:

name: Your Name
email: your.email@example.com
orcid: 0000-0000-0000-0000         # Optional
url: https://github.com/username   # Optional
affiliations: Your Institution     # Optional
toc: Table of Contents             # Defaults if empty

Note: Leaving values blank will not cause errors, but modify these values carefully.

To view your current settings without modifying them, use:

froggeR::froggeR_settings(update = FALSE)

These settings flow through your projects in this order:

1. config.yml stores your permanent settings (exact location depends on your OS)
2. froggeR reads these when creating new projects
3. Settings populate _variables.yml in your project
4. Quarto documents use these variables automatically

How froggeR manages settings across projects (config.yml)

How froggeR manages settings across projects (_variables.yml)

Note: While you can update these settings at any time, most users find they only need to set them once or very infrequently.

Using Custom Variables in Quarto Documents

froggeR allows you to use variables from your _variables.yml file directly in your Quarto documents:

---
title: "My Document"
author: "{{< var author >}}"
date: "{{< var date >}}"
---

This ensures consistency across all your project documents and makes updates easier to manage.

---

Document Styling with SCSS

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

froggeR allows you to create and manage multiple SCSS files for different styling needs:

froggeR::write_scss(name = "modern_theme")
froggeR::write_scss(name = "presentation_theme")

To use a specific SCSS file in your Quarto document, update the YAML header:

---
title: "My Document"
format:
  html:
    theme:
      - default
      - modern_theme.scss  # Or presentation_theme.scss
---

froggeR will attempt to automate the revision of your YAML header. Don’t be dismayed – we’ll provide you with feedback if this is unsuccessful and provide an example like the code block above to walk you through each step.

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

Theme Colors

The custom.scss template includes common color variables:

/*-- 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;
}

---

Quick Styling Recipes

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);
  }
}

---

Common Issues and Solutions

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

Styling Problems

1. Styles Not Applying

   • Verify custom.scss is listed in YAML under theme
   • Check file location (should be in project root)
   • Ensure no syntax errors in SCSS
   • Try clearing Quarto cache

2. Font Issues

   format:
     html:
       mainfont: "Open Sans"
       monofont: "Fira Code"
       theme:
         - custom.scss

   • Include Google Fonts in YAML
   • Check font name spelling
   • Use web-safe fallbacks

3. Variable Scope

   • Define all variables in scss:defaults
   • Reference variables after definition
   • Use proper SCSS syntax ($variable)

SCSS File Management

1. Project Creation vs. Individual Documents
   • quarto_project() automatically creates custom.scss
   • write_quarto() uses existing custom.scss if available
   • For standalone documents, manually create SCSS with write_scss()

---

Additional Resources

For more advanced SCSS customization options, visit:

• Quarto HTML Themes
• More Theme Options
• Bootstrap Variables

---

Summary

froggeR streamlines document customization:

1. Set up once with froggeR_settings()
2. Style with write_scss()
3. Reuse across all your projects
4. Update easily when needed

Happy styling! 🐸

---

Consistent, professional documents with minimal effort