Customization
and branding

Themes

Bootstrap

Quarto uses the popular Bootstrap library for HTML structure and CSS styles.

Bootstrap

You can use Bootstrap components and classes for special styling

 

[Here's a button](thing.pdf){.btn .btn-primary role="button"}

[Here's another button](thing.pdf){.btn .btn-warning role="button"}

↓

Bootswatch themes

Quarto includes 25 themes from Bootswatch:

• default
• cerulean
• cosmo
• cyborg
• darkly
• flatly
• journal
• litera
• lumen

• lux
• materia
• minty
• morph
• pulse
• quartz
• sandstone
• simplex
• sketchy

• slate
• solar
• spacelab
• superhero
• united
• vapor
• yeti
• zephyr

Changing themes

Specify the custom theme under theme in the YAML settings:

_quarto.yml

format:
  html:
    theme:
      - zephyr

Your turn

1. Go to bootswatch.com and explore the different themes there (use the top navigation bar).
2. Preview your site, then try changing different Bootswatch themes in _quarto.yml.

07:00

CSS and Sass

Theme options

Sometimes we want to change theme settings though

Many common basic options: https://quarto.org/docs/output-formats/html-themes.html#basic-options

Total control with CSS

Crash course in CSS

HTML elements can have IDs and classes

HTML elements can be nested inside each other

You can target HTML elements with different degrees of specificity:

• All <h3> headings

• H3 headings with the class neato

• <a> links that are inside a div with the id quarto-sidebar

Browser inpsector

Explore and edit any HTML and CSS right from your browser.

Sass: CSS, but fancier

variables

rules that use variables

Combining CSS and themes

asdf

Your turn

Create a SCSS file and make a bunch of rules

Branding

CSS is a little inconvenient

• Doesn’t play well across HTML outputs - HTML, slides, and dashboards all use slighlty different underlying HTML
• No easy way to reuse the colors and typography from your CSS customizations in R and Python plots or in PDF documents
• Hard to share consistent, resusable themes with others in your organization (or with the world)

Style guides

Organizations and projects generally have style guides for consistency

Urban Institute

This course! See the colophon

Unified branding with a simple YAML file

Create reports, apps, dashboards, plots and more that match your company’s brand guidelines with a single _brand.yml file.

brand.yml is a simple, portable YAML file that codifies your company’s brand guidelines into a format that can be used by Quarto, Python and R tooling to create branded outputs. Our goal is to support unified, branded theming for all of Posit’s open source tools—from web applications to printed reports to dashboards and presentations—with a consistent look and feel.

Branding can be frustrating

But brand.yml makes it easier

1. Define branding in a single _brand.yml file.

2. Apply that branding across almost all Quarto formats.

brand.yml also works with Shiny!

---
config:
  look: handDrawn
  theme: neutral
---
flowchart LR
    by{brand.yml}
    by-->quarto[Quarto]
    quarto-->quarto-html
    quarto-->quarto-pdf
    quarto-html-->quarto-websites[Websites]
    quarto-html-->quarto-presentations[Presentations]
    quarto-html-->quarto-dashboards[Dashboards]
    quarto-html-->quarto-emails[Emails]
    quarto-pdf-->quarto-typst[Typst]

    by-->R
    R-->r-bslib["{bslib}"]
    r-bslib-->r-thematic["{thematic}"]
    r-bslib-->r-shiny["Shiny for R"]
    r-bslib-->r-rmd["R Markdown"]
    r-bslib-->r-pkgdown["pkgdown"]
    %% r-thematic-->r-ggplot2["{ggplot2}"]
    %% r-thematic-->r-plot["{plot}"]

    by-->Python
    Python-->py-brand_yml["brand_yml"]
    py-brand_yml-->py-shiny[Shiny for Python]
    py-brand_yml-->py-plots[seaborn, matplotlib, etc.]

    classDef implemented fill:#8CE3A0,stroke:#0A2911,color:#0A2911;
    classDef partial fill:#A8E5B9,stroke:#4B8A5D,color:#0A2911;
    classDef in-progress fill:#B3D7FF,stroke:#00254D,color:#00254D;
    classDef highlighted fill:#FFE8DB,stroke:#612200,color:#612200;

    class quarto-websites,quarto-presentations,quarto-dashboards,quarto-typst,py-brand_yml,py-shiny,r-bslib,r-shiny,r-rmd,r-pkgdown implemented;
    class r-thematic,py-plots partial;
    class by highlighted;

    click quarto href "https://prerelease.quarto.org/docs/authoring/brand.html"
    click quarto-typst href "https://quarto.org/docs/output-formats/typst.html" "Typst in Quarto"
    click quarto-presentations href "https://quarto.org/docs/presentations/revealjs/" "Reveal.js in Quarto"
    click quarto-dashboards href "https://quarto.org/docs/dashboards/" "Dashboards in Quarto"
    click r-shiny href "https://shiny.posit.co/"
    click r-bslib href "https://rstudio.github.io/bslib/"
    click r-thematic href "https://rstudio.github.io/thematic/"
    click r-ggplot2 href "https://ggplot2.tidyverse.org/"
    click r-rmd href "https://rmarkdown.rstudio.com/"
    click py-shiny href "https://shiny.posit.co/py/"
    click py-brand_yml href "pkg/py/"

brand.yml works with a variety of open source projects, including all the Quarto outputs we’ll talk about today. as well as Shiny for R and Shiny for Python. This means you can define your organization’s branding in a brand.yml file once, and then apply it all over relatively effortlessly.

over the course of this workshop, we’ll use the same brand file to apply to all our outputs

brand.yml elements

• meta: Identifying information, name of the company, URLs, etc.
• logo: Files or links to the brand’s logos.
• color: Colors in the brand’s color palette.
• typography: Fonts for different elements.
• defaults: Additional context-specific settings.

_brand.yml structure

_brand.yml

meta:
  name: World Happiness Report
  link:
    home: https://www.worldhappiness.report/

logo:
  images:
    icon:
      path: images/whr_logo.png
      alt: World Happiness Report icon.
  small: images/whr_logo.png

color:
  palette:
    dark-purple: "#93358c"
    light-purple: "#f8f6fb"
    teal: "#04afaf"
    dark-blue: "#086992"
    hot-pink: "#eb068c"
    light-blue: "#1aade4"

  background: light-purple
  foreground: black
  primary: dark-purple
  secondary: hot-pink
  tertiary: light-blue
  dark: black

typography:
  fonts:
    - family: Libre Franklin
      source: google
      weight: [400, 700]

  base:
    family: Libre Franklin
    weight: 400

  headings:
    family: Libre Franklin
    weight: 700
    color: dark-purple

  link:
    color: primary
    decoration: none

define your brand’s color palette and map your palette to the roles colors play. the semantic colors – primary, foreground, etc

if this seems like a lot of details, don’t worry! we will show you how to make your own file later. for now, it’s enough to just have a general understanding of the different parts

How to apply brand.yml to Quarto

1. Define branding in _brand.yml.
2. Save in the root directory of your Quarto project.

Quarto will detect the presence of _brand.yml and automatically apply the brand to all documents of the supported formats in the project.

If your brand file has a different name or lives in a subdirectory, use the brand key.

my-document.qmd

---
title: "World Happiness Report"
subtitle: "Happiness Trends and Contributing Factors (2011-2024)"
format: html
brand: org_theme.yml
---

use this if you have a file named something other than brand.yml or it lives elsewhere.

Disable brand.yml

To turn off brand.yml for a document, use brand: false.

my-document.qmd

---
title: "World Happiness Report"
subtitle: "Happiness Trends and Contributing Factors (2011-2024)"
format: html
brand: false
---

brand shortcode

Access some brand.yml values with a shortcode.

my_document.qmd

{{< brand color primary >}}

Your turn

05:00

What about plots?

The plots, at least for the R version, are unbranded. how can we apply brand.yml to plots too?

Theme helpers

The quarto packages contain theme helpers that apply branding to plots.

• R
• Python

library(quarto)

my_theme <- theme_brand_ggplot2("_brand.yml")

#| eval: false
#| echo: true
from quarto import theme_brand_plotnine

my_theme = theme_brand_plotnine('_brand.yml')

There are other theme helpers for other plotting libraries

R: https://quarto-dev.github.io/quarto-r/articles/theme-helpers.html

Python: https://github.com/quarto-dev/quarto-python?tab=readme-ov-file#theme-helpers

Your turn

05:00

The R function applies theme_minimal().

brand.yml packages

Access and apply specific brand elements.

• R
• Python

library(brand.yml)

brand <- read_brand_yml("_brand.yml")

brand$color$primary

#| eval: false
#| echo: true
from brand_yml import Brand

brand = Brand.from_yaml("_brand.yml")

brand.color.primary

Templates

What’s next?

Course outline

• ✅ Intro to Quarto
• ✅ Creating basic websites
• ✅ Advanced website features
• ✅ Publishing
• ✅ Customization and branding
• Interactivity

Break!