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.
self-contained: true will embed all resources (CSS, JS, images) directly into the HTML file, making it portable and easy to share. However, it can increase the file size significantly, especially if you have large images or complex styles.

By default, when you render a .qmd file, it will generate a _files folder that contains all the resources (CSS, JS, images) needed for the HTML output. If you move the HTML file without the _files folder, it will break the links to those resources and cause rendering issues.

For example, if you render report.qmd to HTML:
```
quarto render report.qmd --to html
```
Then the following output will be generated:
```
report.html
report_files/
```
If you have self-contained: true in your YAML, the standalone report.html will include all the resources embedded within it.

If you have embeded external CSS style sheets, e.g., css: /path/to/custom-style.css, in order to render your qmd successfully, you need to set self-contained: true to embed the CSS file into the HTML output. Otherwise, you will get an error like Error: /path/to/custom-style.css (404 Not found).
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]

See HTML basic yaml for basic option settings.
See HTML format reference for a complete list of all available options.

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:

Add the font file to your project, e.g., assets/fonts/Georgia Pro/GeorgiaPro-Regular.ttf.
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.
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:

Quarto document: https://quarto.org/docs/output-formats/html-themes.html
Check sass variables: https://bootswatch.com

Docx Document

Quarto supports docx output. You can use a custom docx template to control the styles of your document.

Assume you have a custom docx template custom-reference.docx in your project directory. You can specify it in the YAML header of your qmd file:

format:
  docx:
    reference-doc: custom-reference-doc.docx
    lang: en

When you render the qmd file to docx, Quarto will use the specified template to format the output document.

When you want to change the styles of your docx output, you can edit the custom-reference.docx template and re-render the qmd file. The changes will be reflected in the output docx document.

lang: en specifies the language of the document. This can affect hyphenation, spell checking, and other language-specific features in the output document. en is for American English; en-GB for British English.

See HERE for a complete list of metadata options for docx output.

ref:

Word Templates