6.6 HTML Theming

One simple theme

title: "My Document"
format:
  html: 
    theme: cosmo
    fontsize: 18px
    linestretch: 1.7
    toc: true
    css: /Users/menghan/Library/CloudStorage/OneDrive-Norduniversitet/_shared-resources/custom-style.css
    self-contained: true
    html-math-method: mathjax
    include-in-header: /Users/menghan/Library/CloudStorage/OneDrive-Norduniversitet/_shared-resources/mathjax.html
    grid:
      body-width: 1000px

  • fontsize: set base font size. Can be set in absolute units like 16px, 14pt, or relative units like 1.2em, 120%.

    See HERE for an overview of CSS font-size units.

    Note the attribute fontsize has no dash; distinguish from the CSS property font-size with a dash.

    I prefer to use fontsize: 18px together with cosmo, as I feel the default font size in cosmo is a bit small.

    fontsize: 18px in YAML will be resolved to --bs-root-font-size: 18px; in Bootstrap CSS, which is the base font size for the entire document.

    Q: Which unit should I use?
    A: px for screen display, pt for print.

    px pixels are optimized for screen display, browsers has better support for px and it is more consistent across different devices.

    pt will force fixed font size regardless of user settings or screen scaling. px is useful in @media print CSS rules to ensure that printed text is a specific size.

    Alternatively, you can set font size in your custom SCSS file, e.g.,

    // Default font size
$font-size-base: 1rem; // 16px

    $font-size-base is used by Bootstrap to set the base font size for the body text. When you reset $font-size-base, all other font sizes that are defined in terms of it will also be updated accordingly.

  • gird/body-width: set the max width of the page content. By default, Quarto uses 800px. If you want to use the full width of the page, use page-layout: full instead.

Enable dark and light modes

format:
  html:
    include-in-header: themes/mathjax.html
    respect-user-color-scheme: true
    theme:
      dark: [cosmo, themes/cosmo-dark.scss]
      light: [cosmo, themes/cosmo-light.scss]

respect-user-color-scheme: true honors the user’s operating system or browser preference for light or dark mode.

Otherwise, the order of light and dark elements in the theme or brand will determine the default appearance for your html output. For example, since the dark option appears first in the first example, a reader will see the light appearance by default, if respect-user-color-scheme is not enabled.

As of Quarto 1.7, respect-user-color-scheme requires JavaScript support: users with JavaScript disabled will see the author-preferred (first) brand or theme.

Custom Themes

Your custom.scss file might look something like this:

/*-- 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);
}

Note that the variables section is denoted by

  • /*-- scss:defaults --*/: the defaults section (where Sass variables go)

    Used to define global variables that can be used throughout the theme.

  • /*-- scss:rules --*/: the rules section (where normal CSS rules go)

    Used to define more fine grained behavior of the theme, such as specific styles for headings, paragraphs, and other elements.

Theme Options

You can do extensive customization of themes using Sass variables. Bootstrap defines over 1,400 Sass variables that control fonts, colors, padding, borders, and much more.

The Sass Variables can be specified within SCSS files. These variables should always be prefixed with a $ and are specified within the respective theme files rather than within YAML options.

For instance, I use cosmo together with custom SCSS files cosmo-dark.scss and cosmo-light.scss to customize the dark and light modes of the cosmo theme, respectively. If I want to change the Sass variables, I need to specify the variables in both cosmo-dark.scss and cosmo-light.scss. It seems to be repetitive to specify the same variables in both files, but it is necessary for it to work in dark and light themes.

Commonly used Sass variables:

Variable Description
Colors
$body-bg The page background color.
$body-color The page text color.
$link-color The link color.
$input-bg The background color for HTML inputs.
$popover-bg The background color for popovers (for example, when a citation preview is shown).
Fonts
$font-size-base Base font size for the body text (<body>).
$font-size-root Base font size for the entire document, i.e., what rem is based on. By default, this is usually set to 16px.

You can see all of the variables here:

https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss

When you wonder what is used on your website, use the browser’s developer tools to inspect the CSS variables. Go to “Source” tab, in “Style Sheets” folder, find your .scss file. You will see the variable resolved values in the :root section.

Note that when you make changes to your local .scss, the changes will be implemented in-time. That is, you don’t need to re-build your website to see the effects.

Font Family

If Safari does not display the font you specified but Chrome displays correctly, it is usually due to Safari is striter about system font access. In this case, you can attach the font file and explicitly load the font using @font-face in your custom SCSS file.

For example:

  1. Add the font file to your project, e.g., assets/fonts/Georgia Pro/GeorgiaPro-Regular.ttf.

  2. In _quarto.yml, add the following to tell Quarto to include the font file in the output direcotry, in my case docs:

    format:
  html:
    resources: assets/

    This will copy the assets folder to the output directory.

  3. Add the following code to your html header files:

    <style>
@font-face {
  font-family: "Georgia Pro";
  src: url("assets/fonts/Georgia Pro/GeorgiaPro-Regular.ttf") format("truetype");
  font-weight: 400;
  font-style: normal;
}
</style>

    This will load the “Georgia Pro” font from the specified path and make it available for use in your CSS. You can then set the font-family property to “Georgia Pro” in your theme or custom styles to apply it to your document.

Ref: