Customizing Appearance

Themes

qrtdown uses Quarto’s built-in themes. Set the theme in _qrtdown.yml:

template:
  theme: flatly

Available Themes

Popular options include:

  • cosmo (default) - Classic Bootstrap look
  • flatly - Flat design with subtle shadows
  • litera - Clean, minimal style
  • lumen - Light, readable
  • minty - Fresh green accents
  • sandstone - Warm, earthy tones
  • simplex - Simple and minimal
  • yeti - Friendly and approachable

See the complete list at Quarto HTML Themes.

Code Formatting

Control how long code lines are displayed:

template:
  theme: cosmo
  code_overflow: wrap

Options for code_overflow:

Value Behavior
wrap Long lines wrap to next line (default)
scroll Horizontal scrollbar for long lines
none No special handling

Font Sizes

qrtdown uses conservative font sizes matching pkgdown’s Bootstrap 5 defaults. These are configured in _qrtdown.yml:

template:
  theme: cosmo
  fontsize: 1rem           # Base font size (16px)
  headings:
    h2: 1.75rem            # 28px
    h3: 1.25rem            # 20px
    h4: 1.1rem             # 17.6px
    h5: 1rem               # 16px

These settings generate a _qrtdown-styles.css file that’s applied to your site. This file is regenerated on each build, so edit _qrtdown.yml to customize fonts, not the CSS file directly.

Using Quarto’s Brand System

If you have a brand.yml or _brand.yml file in your package root, qrtdown will detect it and skip its own font customization. This lets you use Quarto’s brand system for consistent styling.

To use brand.yml:

  1. Create brand.yml in your package root
  2. Configure fonts, colors, and logos per Quarto docs
  3. Run build_site() - qrtdown defers to your brand config

Example brand.yml:

color:
  primary: "#2c3e50"
typography:
  base:
    size: 1rem
  headings:
    weight: 600

Complete Appearance Configuration

Here’s the full template section with all options:

template:
  # Quarto theme
  theme: cosmo

  # How to handle long code lines
  code_overflow: wrap

  # Font sizes (skipped if brand.yml exists)
  fontsize: 1rem
  headings:
    h2: 1.75rem
    h3: 1.25rem
    h4: 1.1rem
    h5: 1rem

Custom CSS

For advanced customization beyond themes, you can add custom CSS. Create a styles.css file in your package root and reference it:

template:
  theme: cosmo
  css: styles.css

Then add your custom styles:

/* styles.css */
.navbar {
  background-color: #2c3e50;
}

code {
  color: #e74c3c;
}

Note: If you use custom CSS along with qrtdown’s font settings, both will be applied.

Quick Reference

Setting Location Default
Theme template.theme cosmo
Code overflow template.code_overflow wrap
Base font size template.fontsize 1rem
Heading sizes template.headings pkgdown defaults
Custom CSS template.css none
Brand config brand.yml none (overrides font settings)