Themes

Any Bootswatch theme, a light theme and a dark theme together, and your own CSS.

A theme is a stylesheet that sets the colours and the fonts of the site. The pages of smalldocs use Bootstrap, a library of CSS. Bootswatch is a set of free themes for Bootstrap. smalldocs includes the 25 themes of Bootswatch 5.3, as the CSS files that Bootswatch builds. To use a theme, give its name in theme, at the top level of _smalldocs.yml:

theme: flatly

In a _quarto.yml, theme is under format.html.

The themes have these names:

cerulean, cosmo (the default), cyborg, darkly, flatly, journal, litera, lumen, lux
materia, minty, morph, pulse, quartz, sandstone, simplex, sketchy, slate
solar, spacelab, superhero, united, vapor, yeti and zephyr

The name bootstrap gives Bootstrap with no theme.

A light theme and a dark theme

If you give two themes, the navbar or the sidebar gets a toggle between them. The browser keeps the choice of the reader. This site uses two themes:

theme:
  light: cosmo
  dark: darkly

How the page gets the colours of the theme

Bootswatch writes each theme in Sass, a language that a compiler turns into CSS. smalldocs uses the CSS that Bootswatch builds, so it needs no Sass compiler. A Bootstrap 5.3 theme sets its colours, fonts and borders as CSS variables, such as --bs-primary, --bs-body-bg and --bs-border-color.

The stylesheet of smalldocs lays out the navbar, the sidebar, the table of contents, the callouts and the listings. It uses only those variables. So each part of the page gets the colours of the theme, in the light theme and in the dark theme.

Your own CSS

theme: cosmo
css: styles.css

The browser loads styles.css after the theme and after the stylesheet of smalldocs. In it, set the variables of Bootstrap to change the theme, or the variables of smalldocs to change the layout:

:root {
  --bs-primary: #7a3e9d;     /* the colours of Bootstrap */
  --sd-body-width: 900px;    /* the width of the text */
  --sd-sidebar-width: 280px; /* the width of the sidebar */
}

smalldocs does not compile a .scss file in theme. The build gives a warning about it.