Quarto Styling, Flawed Understanding of

Original Goal

We wanted to use styling to customize features in the website and then the web book. Quarto documentation was supposed to tell how to make those changes, but it wasn't always accurate.

Quarto Documentation

Quarto describes multiple places where configurations can be defined, and then we found a few more:

• Site-wide formats in _quarto.yml which holds the Quarto Project Metadata
  • This includes a format:html section where HTML Options are defined. These can include a subset of total possible CSS options
• Directory or file headers which are merged with _quarto.yml in according to Metadata Merging Rules
• HTML Options can specify additional file(s)
  • CSS Styles as additional file(s)
  • A predefined theme in SCSS
  • More About Quarto Themes including references to Bootstrap and SCSS
  • Additional SCSS Styles as additional file(s) listed along with the theme
• ojs includes options for styling figures that are documented at Observable Plot (sorta). Or maybe Observable JS (in the context of Notebooks).

"In addition to the above Sass variables, Bootstrap itself supports hundreds of additional variables. You can learn more about Bootstrap’s use of Sass variables or review the raw variables and their default values." from the very bottom of HTML Theming. That's right. "Theming" as a verb.

The Flawed Understanding

The key is that Quarto is transforming Markdown files to HTML files to make the website. Quarto aims to provide infinite options for styling, and to have these apply on a mobile device as nicely as in a big browser window. To accomplish this, it uses a variety of technologies.

Definitions

CSS: Cascading Style Sheets is a language that defines how HTML elements are to be displayed. These commands can be in the HTML file or in an external file that is referenced within the HTML of a webpage. CSS associates HTML tags (like <h1> for a header) with qualities like size, color, alignment, etc.:

body {
  background-color: lightblue;
}

h1 {
  color: white;
  text-align: center;
}

Sass: Syntactically Awesome Style Sheets is a stylesheet language that’s compiled to CSS that is saved in a file that can be used in a website. It has two syntaxes: SCSS (.scss) is a superset of CSS such that all valid CSS is also valid SCSS; and the Sass syntax (.sass) uses indentation instead of curly braces to nest statements and newlines instead of semicolons. Sass allows variables, arguments, loops, and nested definitions. Here is an example of SCSS:

$primary-color: #3bbfce;

.content-navigation {
  border-color: $primary-color;
  color: darken($primary-color, 10%);
}

and Sass:

$primary-color: #3bbfce

.content-navigation 
  border-color: $primary-color
  color: darken($primary-color, 10%)

Bootstrap: A development framework that can create responsive websites using, essentially, a whole bunch of special CSS cases. Bootstrap is built with Sass; Bootstrap has default values for a set of SCSS variables which results in standard looks like the big black buttons. HTML documents rendered with Quarto use Bootstrap 5 by default, so would have this default look.

Bootswatch: Bootswatch is a set of free themes for Bootstrap. Quarto includes 25 of these so you don't have to start with the default Bootstrap look.

Putting it Together

So what seems to be happening with the overlapping methods of Quarto styling is:

• Before rendering, Quarto merges document, directory, and project (global) options. Document level options take priority, followed by directory options and finally project-level options.
• If that merged result defines a format, then those rules are applied during the render.
• If the format block contains a css file definition, then the rules defined in the file are applied.
• If the format block contains a list of theme elements, then those rules will clobber all the others - perhaps with Bootstrap defaults.
  • Quarto has a set of SCSS variables that it prioritizes, but it is unclear why those or what the result of that is.
• If you want to adjust the clobbering, add a .scss file to the list of theme elements and put your new options in there. That seems to be the last rules applied so should have ultimate control.

How to Learn More

Use the Inspect option on a browser and navigate to the element in the webpage that concerns you. The CSS options and their origins will appear in the sidebar. Crossed out options have been clobbered by rule that was applied "later". You can interactively deactivate rules with the checkboxes or change values by highlighting them.

To find out what variable (option?) controls what quality, you can look at the Bootstrap Docs. The format of the Component commands (i.e. for Buttons) HTML, not SCSS or CSS format, there are good examples that at least hint at which does what.