Defaults

Warning

This section still reflects the brand.yml spec during design. It will be updated shortly to reflect the current brand.yml specification.

About

Individual formats and outputs can expose format-specific variables or options that are relevant to branding. These options are tied to a specific output format or context, so they can’t be included in the core brand specification. But they are still relevant to the brand and need a place within brand.yml.

For example, Quarto slides expose a set of Sass variables while HTML documents and Shiny apps use Sass variables set by Bootstrap.

On the other hand, some theme-relevant settings are actually format options, or are built on top of a base of format options. For example, when creating a branded Beamer presentation, its often easier to start with a known theme or colortheme. Or similarly, it might be easier in Bootstrap to start with a Bootswatch theme.

A source of inspiration for this section is pkgdown’s approach to template packaging, where a source template provides the initial values for _pkgdown.yml settings that can be overridden in local instances. In this regard, the template section provides a template for the initial values of format- or output-specific settings. An alternative name for this section could be settings.

Example

brand.yml

defaults:
  quarto:
    format:
      html:
        toc: true
        toc-location: left
      beamer:
        navigation: horizontal
        theme: AnnArbor
        colortheme: lily
    website:
      body-footer: Copyright 2022-2024 Posit Software, PBC
  bootstrap:
    defaults:
      enable-rounded: false
      link-decoration: none

Spec

- id: brand-defaults
  description: >
    Additional format or output-specific options, used as a template
    for these settings in those contexts.
  object:
    properties:
      quarto:
        object:
          properties:
            format:
              description: Quarto format options.
              schema: object
            website:
              description: Quarto `website` options.
              schema: object
            book:
              description: Quarto `book` options.
              schema: object
      bootstrap:
        description: Bootstrap theme settings, similar to `bslib::bs_theme()`.
        object:
          closed: true
          properties:
            uses: string
            functions: string
            defaults:
              description: Sass variables.
              schema: object
              namingConvention: kebab-case
            mixins: string
            rules: string
      shiny:
        description: Settings specific to Shiny applications.
        schema: object

Sources

Bootstrap

Some of the most basic non-color concepts found in

• https://getbootstrap.com/docs/5.3/customize/options/
• https://getbootstrap.com/docs/5.3/customize/css-variables/

If we have a deafults.bootstrap field, it would support the named sections used by theme Sass files in Quarto.

HTML basic options

Example from Quarto HTML documentation:

---
title: "My Document"
format:
  html:
    theme: cosmo
    fontsize: 1.1em
    linestretch: 1.7
---

Beamer options

Example from Quarto slides with beamer documentation

---
format:
  beamer:
    aspectratio: 32
    navigation: horizontal
    theme: AnnArbor
    colortheme: lily
---