gh-posit-dev-skills-quarto/skills/brand-yml/references/quarto.md

Using brand.yml with Quarto

Guide for applying brand.yml styling to Quarto documents, presentations, websites, and PDFs.

Overview

Quarto automatically integrates _brand.yml to provide unified visual styling across multiple output formats including HTML, dashboards, RevealJS presentations, and Typst PDFs.

Quick Start

Place _brand.yml at your project root:

my-project/
├── _quarto.yml
├── _brand.yml
├── index.qmd
└── ...

Quarto automatically discovers and applies _brand.yml - no configuration needed.

Supported Formats

Brand styling automatically applies to:

• HTML documents - Web pages, reports
• HTML dashboards - Interactive dashboards
• RevealJS presentations - Slide decks
• Typst PDFs - PDF documents via Typst
• Websites - Multi-page Quarto websites

Document-Level Usage

Specify brand in document frontmatter:

---
title: "My Document"
format:
  html:
    brand: _brand.yml
---

Or use default discovery:

---
title: "My Document"
format: html
---

If _brand.yml exists at project root, it's automatically applied.

Project-Level Usage

Configure in _quarto.yml:

project:
  type: website
  brand: _brand.yml

format:
  html:
    theme: default

Custom Brand File Location

Specify a non-standard path:

---
title: "My Document"
format:
  html:
    brand: branding/company-brand.yml
---

Or in project config:

project:
  brand: path/to/brand.yml

Light/Dark Mode

Specify color variants for light and dark modes:

color:
  palette:
    blue: "#0066cc"
  primary:
    light: "#0066cc"
    dark: "#3399ff"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"
  foreground:
    light: "#333333"
    dark: "#e0e0e0"

Any color in color or typography can have light/dark variants.

Theme Layering

Control precedence with the "brand" keyword:

Default (Brand Lowest Priority)

format:
  revealjs:
    theme:
      - custom.scss
      - cosmo

Priority: cosmo > custom.scss > _brand.yml

Brand Highest Priority

format:
  revealjs:
    theme:
      - cosmo
      - custom.scss
      - brand

Priority: _brand.yml > custom.scss > cosmo

Brand in Middle

format:
  html:
    theme:
      - cosmo
      - brand
      - custom.scss

Priority: custom.scss > _brand.yml > cosmo

Accessing Brand Data in Documents

Shortcodes

Use shortcodes to access brand values (requires Quarto extensions):

<!-- Access colors -->
Our primary color is {{{< brand-color primary >}}}.

<!-- Access meta information -->
Welcome to {{{< brand-meta name >}}}.

SCSS Variables

Access brand colors in custom SCSS:

// Custom SCSS file
.branded-element {
  color: $brand-primary;
  background: $brand-background;
  border-color: $brand-secondary;
}

Brand colors are automatically available as Sass variables: $brand-{color-name}.

Typst PDF Support

Brand styling works with Typst PDF output:

---
title: "My Document"
format:
  typst:
    brand: _brand.yml
---

Typst Color Variables

Access colors in Typst templates:

• brand-color.{name} - Palette colors (e.g., brand-color.blue, brand-color.primary)
• brand-background-color.{name} - Lighter background variants

Typst Typography Support

Element	family	weight	color	background-color	line-height
base	✓	✓	✓	-	✓
headings	✓	✓	✓	-	✓
title	✓	✓	✓	-	✓
monospace-inline	✓	✓	✓	✓	-
monospace-block	✓	✓	✓	✓	✓
link	-	✓	✓	✓	-

Typst Font Handling

Quarto automatically downloads Google Fonts and caches them for Typst. Check fonts:

quarto typst fonts --ignore-system-fonts --font-path .quarto/typst-font-cache/

Disable font fallback in Typst:

#set text(fallback: false)

Complete Examples

Simple HTML Document

---
title: "Quarterly Report"
format:
  html:
    toc: true
---

# Executive Summary

Content here uses brand colors and typography automatically.

With _brand.yml at project root:

color:
  palette:
    blue: "#0066cc"
  primary: blue
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 16px
  headings:
    family: Inter
    weight: 600

RevealJS Presentation

---
title: "Company Overview"
format:
  revealjs:
    theme:
      - default
      - brand
    logo: logo.png
---

# Introduction

Slides automatically use brand colors and fonts.

Website with Brand

_quarto.yml:

project:
  type: website
  brand: _brand.yml

website:
  title: "My Company"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css

Brand colors and typography apply across all pages.

Dashboard

---
title: "Sales Dashboard"
format:
  dashboard:
    brand: _brand.yml
    theme: default
---

## Row

```{python}
# Dashboard content

### Typst PDF

```yaml
---
title: "Technical Report"
format:
  typst:
    brand: _brand.yml
    margin:
      x: 2cm
      y: 2cm
---

# Overview

PDF uses brand colors and fonts via Typst.

Brand Extensions

Create reusable brand packages:

quarto create extension brand

Structure:

my-brand-extension/
├── _extension.yml
├── brand.yml
├── logo.png
└── fonts/
    └── ...

_extension.yml:

title: Company Brand
author: Your Name
version: 1.0.0
contributes:
  brand: brand.yml

Install extension in projects:

quarto add username/my-brand-extension

Requirement: Brand extensions need _quarto.yml project file.

Sample _brand.yml for Quarto

Minimal example:

color:
  palette:
    brand-blue: "#0066cc"
    brand-gray: "#666666"
  primary: brand-blue
  foreground: brand-gray
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2

Complete example with light/dark mode:

meta:
  name: My Company
  link: https://mycompany.com

logo:
  small: logo-icon.png
  medium:
    light: logo-dark.svg
    dark: logo-white.svg

color:
  palette:
    blue: "#0066cc"
    navy: "#003366"
    gray: "#666666"
    light-gray: "#f5f5f5"
  primary: blue
  secondary: gray
  success: "#28a745"
  info: blue
  warning: "#ffc107"
  danger: "#dc3545"
  foreground:
    light: navy
    dark: "#e0e0e0"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 500, 600, 700]
      style: [normal, italic]
    - family: Fira Code
      source: google
      weight: [400, 500]
  base:
    family: Inter
    size: 1rem
    line-height: 1.6
  headings:
    family: Inter
    weight: 600
    line-height: 1.2
  monospace:
    family: Fira Code
    size: 0.9em
  link:
    color: primary
    weight: 500

Tips

• Automatic discovery: Place _brand.yml at project root for automatic application
• Light/dark variants: Use for websites with theme toggles
• Layer strategically: Use brand keyword to control theme precedence
• Test across formats: Verify brand applies correctly to HTML, PDF, and presentations
• Extension for reuse: Create brand extensions for multi-project consistency
• Version control: Include _brand.yml in git repository

Troubleshooting

Brand not applying?

• Verify file is named _brand.yml (with underscore)
• Check file is at project root or specified in brand: field
• Ensure _quarto.yml exists for project-level branding
• Try explicit path in frontmatter

Colors not matching?

• Ensure hex colors have quotes: "#0066cc"
• Check color references match palette definitions
• Verify theme layering order

Fonts not loading?

• Verify Google Fonts spelling
• Check internet connection (required for Google Fonts)
• For Typst, check font cache: quarto typst fonts
• Ensure source: google is specified correctly

Typst-specific issues?

• Check font cache path: .quarto/typst-font-cache/
• Add #set text(fallback: false) to debug font issues
• Verify typography properties are supported (see table above)

Brand extension not working?

• Ensure _quarto.yml exists in project
• Verify extension is installed: quarto list extensions
• Check extension contributes brand: look for contributes.brand in _extension.yml