--- title: "Building Your Brand Identity" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Building Your Brand Identity} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## 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: ```yaml # 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: ```r > 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): ```r 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: ```r 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): ```r 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: ```r 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: ```r 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: ```r > 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: ```r 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: ```r > 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\\AppData\Local\froggeR\_brand.yml` - Used as default for all new projects ## Next Steps Now that you understand branding with `brand_settings()`, explore: - [Your Metadata, Your Way](your-metadata-your-way.html) - Learn about `settings()` - [Set Once, Use Everywhere](set-once-use-everywhere.html) - Understand global configuration philosophy - [From Zero to Project in Seconds](from-zero-to-project.html) - See how `quarto_project()` uses your branding ## 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.