Skip to contents

Building Your Brand Identity

Source: vignettes/building-your-brand-identity.Rmd
building-your-brand-identity.Rmd

Introduction

Your documents tell a story through their visual presentation. Consistent branding makes your work recognizable, professional, and polished.

The brand_settings() function helps you create and manage a unified visual identity for all your Quarto projects. Whether you’re a research lab, data science team, or individual consultant, brand_settings() ensures your documents maintain consistent colors, logos, and typography.

What Is Quarto Branding?

Quarto 1.6+ supports branding through _brand.yml files, allowing you to centralize:

  • Project/organization name: Used in document headers
  • Colors: Primary brand colors and extended palettes
  • Logos: Large and small logo variants
  • Typography: Font families, sizes, and styles
  • Additional styling: Links, code, headings

Flexible Brand Configuration: Two Approaches

froggeR offers two complementary ways to configure your brand, balancing ease-of-use with comprehensive customization. This ensures you can quickly set up core branding elements while retaining full control over advanced options.

Core Elements (Interactive)

The most impactful branding elements are configured through an interactive prompt:

  • Project/organization name: What appears in document headers
  • Primary color: Your main brand color (hex format)
  • Logo - large: Full-size logo for headers
  • Logo - small: Icon/favicon for compact displays

Advanced Options (Template)

For specialized or advanced branding needs, froggeR provides access to the complete _brand.yml template (gists/brand.yml within the package). This allows direct editing of all available options, including:

  • Typography: Font families, sizes, weights, styles
  • Color palette: Secondary, tertiary, and extended colors
  • Links: Custom link colors and hover effects
  • Code styling: Monospace fonts and inline code appearance
  • Headings: Individual heading level customization
  • Logo metadata: Alt text, links, and sizing parameters

This full template is based on the gists/brand.yml file used internally by write_brand(). A snippet of the template looks like this:

# Example of the full _brand.yml template (gists/brand.yml)
meta:
  name: ""
  # ... other meta options ...
color:
  palette:
    primary: ""
    # ... other color options ...
logo:
  large: ""
  small: ""
  # ... other logo options ...
typography:
  font-family-sans: ""
  # ... other typography options ...
# ... and so on for links, code, headings

To customize these, select ‘Edit the full template for advanced options’ above.

The Interactive Workflow

First-Time Setup with Dr. Rachel Kim

Rachel runs brand_settings() for the first time:

> froggeR::brand_settings()

froggeR Brand Configuration
✖ No project-level branding
✖ No global branding

What would you like to do?

1: Create or update branding
2: View current branding
3: Exit

Selection: 1

froggeR proceeds to Core Elements (Interactive):

Configure your branding (Core Elements - Interactive)

Project or organization name
  Used in document headers and branding
  : Kim Lab

Primary brand color
  Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
  : #1E3A8A

Logo path - large
  Path to large logo (e.g., logos/logo-large.png)
  : logos/kim-lab-logo.png

Logo path - small
  Path to small/icon logo (e.g., logos/logo-icon.png)
  : logos/kim-lab-icon.png

After entering Core Elements fields, froggeR shows a preview:

Your branding configuration (Core Elements):

---
meta:
  name: Kim Lab

logo:
  large: logos/kim-lab-logo.png
  small: logos/kim-lab-icon.png

color:
  palette:
    primary: #1E3A8A
---

Next, froggeR shows available Advanced Options (Template):

Available for advanced customization (Advanced Options - Template):

* Typography: fonts, families, sizes, styles
* Colors: additional color palette options
* Links: custom link colors and styling
* Code: monospace font and inline code styling
* Headings: custom heading colors and styles
* Logo meta: alt text, links, sizing

To customize these, select 'Edit the full template' above.

Rachel saves with the basics:

What would you like to do?

1: Save with these basics
2: Edit the full template for advanced options
3: Cancel (discard changes)

Selection: 1

Where would you like to save this branding?

1: Save to this project only
2: Save globally (reuse in all future projects)
3: Save to both locations
4: Cancel (discard changes)

Selection: 2

✔ Saved to global: /home/rachel/.config/froggeR/_brand.yml

✔ froggeR branding configured successfully!

ℹ Your branding will automatically be used in future froggeR projects.

Input Validation: Hex Color Format

froggeR validates color inputs for proper hex format:

Primary brand color
  Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
  : 1E3A8A

  Color must be in hex format: #RRGGBB (e.g., #0066cc) or #RGB (e.g., #06c)

Primary brand color
  Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
  : #1E3A8A

✔

The validator accepts both 6-digit (#RRGGBB) and 3-digit (#RGB) hex formats.

Project-Specific Branding

For specific projects needing different branding:

> froggeR::brand_settings()

# ... navigate to ...

Selection: 1

Branding already exists. What would you like to do?

1: Update existing branding
2: Start fresh

Selection: 2

Choose “Start fresh” to create project-specific branding that doesn’t affect your global settings.

Advanced Customization

For high-profile publications needing custom typography and colors:

Selection: 2
# "Edit the full template for advanced options"

ℹ A branding template will open in your editor for advanced customization.
Configure additional options, then save.

Your editor opens with the complete _brand.yml file including your Core Elements (Interactive) values plus all Advanced Options (Template) available for customization.

Viewing Your Current Branding

At any time, view your configuration:

> froggeR::brand_settings()

froggeR Brand Configuration
✔ Project-level branding found
✔ Global branding found (reuses across projects)

What would you like to do?

1: Create or update branding
2: View current branding
3: Exit

Selection: 2

✔ Project-level branding:

meta:
  name: Sleep Consortium
...

✔ Global branding (used by default in new projects):

meta:
  name: Kim Lab
...

Where Is Branding Stored?

froggeR stores branding in two locations:

  1. Project-level: _brand.yml in your project directory
    • Used by current project only
    • Takes precedence over global branding
    • Committed to version control
  2. Global: Platform-specific configuration directory
    • Linux/macOS: ~/.config/froggeR/_brand.yml
    • Windows: C:\Users\<username>\AppData\Local\froggeR\_brand.yml
    • Used as default for all new projects

Next Steps

Now that you understand branding with brand_settings(), explore:

Summary

The brand_settings() function provides a flexible approach to branding:

  • Core Elements (Interactive): Quick setup of essential elements—name, primary color, logos
  • Advanced Options (Template): Advanced customization when you need fine-grained control
  • Validates input with helpful error messages
  • Stores globally for reuse across all projects
  • Allows project-specific overrides when needed
  • Shows clear previews before saving
  • Provides flexible save options to match your workflow

By configuring branding once with brand_settings(), you create a consistent visual identity across all Quarto projects.