More About Quarto Themes

As a part of Quarto, we’ve developed a simple single file format that describes declarations, variables, and rules that should be layered into Scss files when compiling them into css. The basic structure of a theme file is:

• A single text file that contains valid Scss

• Special comments are used to denote regions of functions, defaults, mixins, and rules (region decorators).

• At least one of these region decorators must be present in order for the theme file to be valid.

• More than one of each type of region decorator are permitted. If more than one of any type is present, all regions of a given type will be merged into a single block of that type in the order in which they are encountered in the file.

• When compiling, the sections will be layered according to type, functions first, then variables, then mixins, then rules.

• The directory that contains your theme file will be added to the load path, allowing @use or @import statements to be resolved using the same directory that contains the theme file.

Here is an example file:

/*-- scss:functions --*/
@function colorToRGB ($color) {
  @return "rgb(" + red($color) + ", " + green($color) + ", " + blue($color)+ ")";
}

/*-- scss:defaults --*/
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
}

Bootswatch Sass Theme Files

We’ve merged Bootswatch themes for Bootstrap 5 into this single file theme format in our repo here:

https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/html/bootstrap/themes

From time to time, as the Bootswatch themes are updated, we will update these merged theme files.

Bootstrap / Bootswatch Layering

When using the Quarto html and dashboard formats, we allow the user to specify theme information in the document front matter (or project YAML). The theme information consists of a list of one or more of

• A valid built in Bootswatch theme name

• A theme file (valid as described above).

For example the following would use the cosmo Bootswatch theme and provide customization using the custom.scss file:

theme:
  - cosmo
  - custom.scss

When compiling the CSS for a Quarto website or HTML page, we merge any user provided theme file(s) or Bootswatch themes with the Bootstrap Scss in the following layers:

Uses
    Bootstrap
    Theme(s)       /*-- scss:uses --*/
    
Functions
    Bootstrap
    Theme(s)       /*-- scss:functions --*/

Variables
    Themes(s)      /*-- scss:defaults --*/
    Bootstrap
    
Mixins                 
    Bootstrap
    Theme(s)       /* -- scss:mixins --*/

Rules
    Bootstrap
    Theme(s)       /*-- scss:rules --*/

We order the themes according to the order that they are specified in the YAML, maintaining the order for declarations and rules and reversing the order for variables (allowing the files specified later in the list to provide defaults variable values to the files specified earlier in the list). Layering of the example themes above would be as follows:

Uses
    Bootstrap
    cosmo           /*-- scss:uses --*/
    custom.scss     /*-- scss:uses --*/

Functions
    Bootstrap
    cosmo           /*-- scss:functions --*/
    custom.scss     /*-- scss:functions --*/

Variables
    custom.scss     /*-- scss:defaults --*/
    cosmo           /*-- scss:defaults --*/
    Bootstrap

Mixins
    Bootstrap
    cosmo            /* -- scss:mixins --*/
    custom.scss      /* -- scss:mixins --*/

Rules
    Bootstrap
    cosmo           /*-- scss:rules --*/
    custom.scss     /*-- scss:rules --*/

revealjs Layering

The same system applies for revealjs and its themes. revealjs themes shipped with Quarto do not have a uniform variable naming convention, and so different SCSS files are likely to be needed to make effective changes to different themes.

Nevertheless, the following examples illustrate what’s possible:

# In this configuration, `custom.scss` takes precedence
format:
  revealjs:
    theme:
      - blood
      - custom.scss
# In this configuration, the `blood` theme takes precedence
format:
  revealjs:
    theme:
      - custom.scss
      - blood

_brand.yml Layering

Quarto supports brand.yml, see the Brand guide for more details. By default, styling information in _brand.yml takes the lowest precedence. To change this, use the "brand" string in your theme configuration in YAML:

# In this configuration, the `blood` theme takes precedence
# over `custom.scss` *and* the information in `_brand.yml`
format:
  revealjs:
    theme:
      - custom.scss
      - blood
# In this configuration, the information in `_brand.yml` takes
# precedence over the `blood` theme and `custom.scss`, in that
# order
format:
  revealjs:
    theme:
      - blood
      - custom.scss
      - brand