Quarto, themes, and you!

Carlos Scheidegger @ Mayo Clinic, 2024-07-09

Tiny bio

• Lead developer for the Quarto project, have worked on the project since joining Posit (fka RStudio) three years ago
• Previous life: computer science academic researcher for over a decade

Housekeeping

• I’m using Quarto 1.5 for this presentation, and discussing features that shipped with Quarto 1.5 (last week).
• It’s very stable. If you can update, I highly recommend it.
• This presentation itself is a Quarto document published at https://quarto.pub: https://posit-carlos.quarto.pub/mayo-clinic-jul-2024.
• The source code for the presentation is on GitHub: https://github.com/cscheid/2024-jul-mayo-clinic-talk

Themes: the present

Quarto themes

• Quarto ships great-looking templates for websites, presentations, PDF reports, dashboards, and more
• It also lets you customize the appearance of all of these formats

Theming HTML documents

• Predefined themes
• CSS
• SCSS
• Create your own format

Note

Quarto is designed to grow with you, and offers you complete extensibility when you need it. (That, of course, comes with a larger needed effort).

Predefined themes

Add to your _quarto.yml configuration, or to document front matter:

format:
  html:
    theme: cerulean

Quarto ships with all 25 bootswatch themes.

Light + dark modes

Add this:

format:
  html:
    theme: 
      light: flatly
      dark: darkly

CSS

Add to your configuration:

format:
  html:
    css: my-styles.css

The CSS stylesheet will be added to your document, and it can be as simple as

body {
    background-color: #90a0c0;
}

SCSS

To unlock deeper configurability of Quarto’s styling, including 1,400+ variables that control fonts, colors, padding, etc, you’ll eventually want to learn SCSS. Add to your configuration:

format:
  html:
    theme: custom.scss

For example:

/*-- scss:functions --*/ // <- these are needed in Quarto!
@function invert($color, $amount: 100%) {
  $inverse: change-color($color, $hue: hue($color) + 180);
  @return mix($inverse, $color, $amount);
}
/*-- scss:defaults --*/
$primary-color: #036;
/*-- scss:rules --*/
.header {
  background-color: invert($primary-color, 80%);
}

Additional resources

• Isabella Velásquez’s Intro to Quarto: https://ivelasq.quarto.pub/intro-to-quarto-2024/#/html-theming

• Emil Hvitfeldt’s Slidecraft series: https://emilhvitfeldt.com/post/slidecraft-colors-fonts/

Roll your own format

Quarto lets you create an entirely new custom format, and then package it so others in your organization can use it.

Caveats

Warning

There’s one annoying Quarto bug we’re going to fix in 1.6: a Quarto project can only have a single SASS theme for all of its documents.

RevealJS presentations

• revealjs is ultimately an HTML format, and so all of the above applies

• The HTML that Quarto emits in revealjs is slightly different from regular webpages, and so the specific themes need to be adapted

PDF reports, 1

• By default, Quarto uses LaTeX for PDF generation
• Customization happens through LaTeX and Pandoc templates
  • https://quarto.org/docs/output-formats/pdf-basics.html#latex-includes
• Consider starting from existing customizations: https://quarto.org/docs/journals/#journal-formats
• Totally different from HTML formats

PDF reports, 2

• Quarto recently added support for Typst: https://typst.app
• More modern PDF generation. Much less mature ecosystem, but more much more easily customizable
• Customization again happens through Pandoc templates (but a different set from LaTeX)
  • https://quarto.org/docs/output-formats/typst.html
  • https://quarto.org/docs/output-formats/typst-custom.html
• Quarto feature highlight: Styled tables, see https://quarto.org/docs/output-formats/typst.html#typst-css

Themes: the (near) future

v1.6 upcoming feature: _brand.yml

• Today: different formats require different theming configurations.

• Quarto lets you write Markdown once and produce websites, reports, books, presentations, emails, etc. So why don’t we do the same thing for themes?

Note

We intend this feature to solve “90%” of the theming requirements across a variety of formats. But, by the very nature of theming customizations, it can never be a substitute for true custom formats. Still, we expect it to be the feature that users reach first for when creating “branded documents”

_brand.yml: sneak peek

logo:
  small: posit-icon.png
  medium: posit.png
  large: posit.svg

_brand.yml: sneak peek

color:
  palette:
    blue: "#447099"
    orange: "#EE6331"
    gray: "#404041"
    white: "#FFFFFF"
    teal: "#419599"
    green: "#72994E"
    burgundy: "#9A4665"
  theme:
    foreground: "#151515"
    background: white
    primary: blue
    secondary: "#707073"
    tertiary: "#C2C2C4"
    success: green
    info: teal
    warning: orange
    danger: burgundy
    light: white
    dark: gray

_brand.yml: sneak peek

typography:
  font:
    - google: "Open Sans"
    - google: "Fira Code"
    - google:
        family: "Roboto Slab"
        weight: 600
        style: normal
        display: block
  base:
    family: "Open Sans"
    line-height: 1.25
    size: 1rem
  headings:
    family: "Roboto Slab"
    color: primary
    weight: 600
  monospace:
    family: "Fira Code"
    size: 0.9em

_brand.yml is more than a Quarto feature

_brand.yml is designed to cut across a wide swath of Posit-supported products. NB: no timeline or promise on any of these!!

• Shiny documents (both R and Python)
• Visualization libraries:
  • concrete plans in R (through thematic, so both base R plots and grid graphics ie ggplot2)
  • designs being considered for Python ecosystem (specifically Matplotlib theming, so plotnine, matplotlib, seaborn)

Acknowledgments

• Emil Hvitfeldt
• Isabella Velásquez
• Rich Iannone (gt + great_tables)
• Gordon + Christophe
• Charlotte + Mine
• Our users

Thank you!