Technical learning notes, conference insights, and development guides
Author

Dario Airoldi

Published

August 8, 2025

Keywords

learning, development, azure, dotnet, conference, documentation

Quarto Theming and Styling

Overview

Quarto provides extensive theming and styling capabilities that allow you to create visually appealing and professionally designed documentation websites. This guide covers all aspects of Quarto’s theming system, from built-in themes to custom styling approaches.

Table of Contents

Built-in Themes

Quarto comes with a variety of professionally designed themes based on Bootstrap and Bootswatch.

Available Themes

format:
  html:
    theme: default    # Clean, minimal design
    # theme: cerulean  # Blue accent theme
    # theme: cosmo     # Flat, modern design
    # theme: cyborg    # Dark theme with cyan accents
    # theme: darkly    # Dark Bootstrap theme
    # theme: flatly    # Flat UI theme
    # theme: journal   # Newspaper-style theme
    # theme: litera    # Typography-focused theme
    # theme: lumen     # Light theme with warm colors
    # theme: lux       # Elegant theme with serif fonts
    # theme: materia   # Material Design inspired
    # theme: minty     # Fresh, green accent theme
    # theme: morph     # Modern, rounded design
    # theme: pulse     # Purple accent theme
    # theme: quartz    # Professional, clean theme
    # theme: sandstone # Warm, earthy theme
    # theme: simplex   # Minimalist theme
    # theme: sketchy   # Hand-drawn, casual style
    # theme: slate     # Dark theme with cool colors
    # theme: solar     # Solarized color scheme
    # theme: spacelab  # Space-themed design
    # theme: superhero # Dark theme with bright accents
    # theme: united    # Orange accent theme
    # theme: vapor     # Retro, neon-inspired theme
    # theme: yeti      # Clean theme with blue accents
    # theme: zephyr    # Light, airy design

Theme Selection Guidelines

  • Default: Best for general documentation
  • Cosmo: Modern, professional look
  • Flatly: Clean, contemporary design
  • Darkly/Cyborg: Dark themes for developers
  • Journal: Academic/research content
  • Lux: Elegant, serif-based design
  • Materia: Material Design aesthetic

Theme Configuration

Basic Theme Setup

# _quarto.yml
project:
  type: website

format:
  html:
    theme: cosmo
    css: custom.css
    toc: true
    code-fold: true

Multiple Theme Options

format:
  html:
    theme: 
      - cosmo
      - custom.scss
    css: 
      - styles.css
      - components.css

Theme-Specific Configuration

format:
  html:
    theme: cosmo
    mainfont: "Open Sans"
    monofont: "Fira Code"
    fontsize: 1.1em
    linestretch: 1.7

Custom CSS Integration

Basic CSS Integration

Create a styles.css file:

/* Custom styles for Quarto site */
:root {
  --primary-color: #3498db;
  --secondary-color: #2c3e50;
  --accent-color: #e74c3c;
  --background-color: #ffffff;
  --text-color: #2c3e50;
}

body {
  font-family: 'Inter', sans-serif;
  color: var(--text-color);
  background-color: var(--background-color);
}

.navbar {
  background-color: var(--primary-color) !important;
}

.btn-primary {
  background-color: var(--accent-color);
  border-color: var(--accent-color);
}

Advanced CSS Customization

/* Typography improvements */
h1, h2, h3, h4, h5, h6 {
  font-weight: 600;
  line-height: 1.2;
  margin-top: 2rem;
  margin-bottom: 1rem;
}

/* Code styling */
pre {
  background-color: #f8f9fa;
  border: 1px solid #e9ecef;
  border-radius: 0.375rem;
  padding: 1rem;
}

code {
  background-color: #f1f3f4;
  padding: 0.125rem 0.25rem;
  border-radius: 0.25rem;
  font-size: 0.875em;
}

/* Callout customization */
.callout {
  border-left: 4px solid var(--primary-color);
  padding: 1rem;
  margin: 1.5rem 0;
  background-color: #f8f9fa;
}

.callout-title {
  font-weight: 600;
  color: var(--primary-color);
}

SCSS Variables and Customization

Creating Custom SCSS Theme

Create a custom.scss file:

/*-- scss:defaults --*/
// Import Google Fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

// Color palette
$primary: #3498db;
$secondary: #95a5a6;
$success: #27ae60;
$info: #17a2b8;
$warning: #f39c12;
$danger: #e74c3c;
$light: #f8f9fa;
$dark: #2c3e50;

// Typography
$font-family-sans-serif: 'Inter', system-ui, -apple-system, sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Layout
$grid-breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
  xxl: 1400px
);

/*-- scss:rules --*/
// Custom component styles
.hero-section {
  background: linear-gradient(135deg, $primary, darken($primary, 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  h1 {
    font-size: 3rem;
    font-weight: 700;
    margin-bottom: 1rem;
  }
  
  .lead {
    font-size: 1.25rem;
    margin-bottom: 2rem;
  }
}

.feature-card {
  background: white;
  border-radius: 0.5rem;
  padding: 2rem;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  transition: transform 0.3s ease;
  
  &:hover {
    transform: translateY(-5px);
  }
  
  .icon {
    font-size: 3rem;
    color: $primary;
    margin-bottom: 1rem;
  }
}

SCSS Variables Reference

// Brand colors
$primary: #your-brand-color;
$secondary: #your-secondary-color;

// Typography
$headings-font-family: 'Your-Heading-Font', sans-serif;
$font-family-base: 'Your-Body-Font', sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Spacing
$spacer: 1rem;
$spacers: (
  0: 0,
  1: $spacer * 0.25,
  2: $spacer * 0.5,
  3: $spacer,
  4: $spacer * 1.5,
  5: $spacer * 3
);

// Borders
$border-radius: 0.375rem;
$border-width: 1px;
$border-color: #dee2e6;

Bootstrap Integration

Bootstrap Classes in Markdown

::: {.container-fluid}

::::{.row}

:::{.col-md-8}
### Main Content
Content goes here
:::

:::{.col-md-4}
### Sidebar
Sidebar content
:::

::::

:::

::: {.alert .alert-info}
**Info:** This is an informational alert using Bootstrap classes.
:::

::: {.btn .btn-primary .btn-lg}
[Large Primary Button](#)
:::

Custom Bootstrap Components

/* Custom button variants */
.btn-outline-custom {
  color: var(--primary-color);
  border-color: var(--primary-color);
}

.btn-outline-custom:hover {
  color: white;
  background-color: var(--primary-color);
  border-color: var(--primary-color);
}

/* Custom card styles */
.card-hover {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card-hover:hover {
  transform: translateY(-5px);
  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
}

/* Custom navbar styles */
.navbar-custom {
  background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
}

Layout Customization

Custom Page Layouts

# In document front matter
---
title: "Custom Layout Page"
format:
  html:
    page-layout: custom
    css: page-styles.css
---

Grid System Customization

// Custom grid system
.custom-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 2rem;
  padding: 2rem 0;
}

.grid-item {
  background: white;
  padding: 1.5rem;
  border-radius: 0.5rem;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// Responsive adjustments
@media (max-width: 768px) {
  .custom-grid {
    grid-template-columns: 1fr;
    gap: 1rem;
    padding: 1rem 0;
  }
}

Typography and Fonts

Font Configuration

format:
  html:
    theme: cosmo
    mainfont: "Source Sans Pro"
    monofont: "JetBrains Mono"
    fontsize: 1.1em
    linestretch: 1.7

Custom Font Integration

// Import fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@300;400;500&display=swap');

// Font variables
$font-family-base: 'Inter', system-ui, sans-serif;
$font-family-monospace: 'JetBrains Mono', 'SF Mono', Consolas, monospace;

// Typography scale
$font-sizes: (
  xs: 0.75rem,
  sm: 0.875rem,
  base: 1rem,
  lg: 1.125rem,
  xl: 1.25rem,
  2xl: 1.5rem,
  3xl: 1.875rem,
  4xl: 2.25rem,
  5xl: 3rem
);

// Apply typography
body {
  font-family: $font-family-base;
  font-size: map-get($font-sizes, base);
  line-height: 1.6;
}

h1 { font-size: map-get($font-sizes, 4xl); }
h2 { font-size: map-get($font-sizes, 3xl); }
h3 { font-size: map-get($font-sizes, 2xl); }

Color Schemes

Defining Color Palettes

// Primary palette
$colors: (
  "primary": #3498db,
  "secondary": #95a5a6,
  "accent": #e74c3c,
  "success": #27ae60,
  "warning": #f39c12,
  "danger": #e74c3c,
  "info": #17a2b8,
  "light": #f8f9fa,
  "dark": #2c3e50
);

// Generate utility classes
@each $name, $color in $colors {
  .text-#{$name} {
    color: $color !important;
  }
  
  .bg-#{$name} {
    background-color: $color !important;
  }
  
  .border-#{$name} {
    border-color: $color !important;
  }
}

Semantic Color Usage

/* Semantic color system */
:root {
  /* Brand colors */
  --brand-primary: #3498db;
  --brand-secondary: #2c3e50;
  
  /* Semantic colors */
  --color-success: #27ae60;
  --color-warning: #f39c12;
  --color-error: #e74c3c;
  --color-info: #17a2b8;
  
  /* Neutral colors */
  --color-text: #2c3e50;
  --color-text-muted: #6c757d;
  --color-background: #ffffff;
  --color-surface: #f8f9fa;
  --color-border: #dee2e6;
}

Responsive Design

Responsive Typography

// Responsive font sizes
@mixin responsive-font-size($min-size, $max-size) {
  font-size: clamp(#{$min-size}, 4vw, #{$max-size});
}

h1 {
  @include responsive-font-size(2rem, 4rem);
  font-weight: 700;
  line-height: 1.1;
}

h2 {
  @include responsive-font-size(1.5rem, 3rem);
  font-weight: 600;
  line-height: 1.2;
}

// Responsive spacing
@media (max-width: 768px) {
  .container {
    padding-left: 1rem;
    padding-right: 1rem;
  }
  
  .section {
    padding-top: 2rem;
    padding-bottom: 2rem;
  }
}

Mobile-First Approach

// Mobile-first responsive design
.feature-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
  
  @media (min-width: 576px) {
    grid-template-columns: repeat(2, 1fr);
    gap: 1.5rem;
  }
  
  @media (min-width: 992px) {
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;
  }
}

Dark Mode Support

Dark Mode Configuration

format:
  html:
    theme: 
      light: cosmo
      dark: darkly

Custom Dark Mode Styles

// Dark mode variables
[data-bs-theme="dark"] {
  --color-background: #1a1a1a;
  --color-surface: #2d2d2d;
  --color-text: #ffffff;
  --color-text-muted: #a0a0a0;
  --color-border: #404040;
}

// Dark mode specific styles
@media (prefers-color-scheme: dark) {
  .custom-component {
    background-color: var(--color-surface);
    color: var(--color-text);
    border-color: var(--color-border);
  }
}

Custom Components

Creating Reusable Components

// Hero section component
.hero {
  background: linear-gradient(135deg, var(--brand-primary), darken(var(--brand-primary), 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  &__title {
    font-size: 3.5rem;
    font-weight: 700;
    margin-bottom: 1rem;
    
    @media (max-width: 768px) {
      font-size: 2.5rem;
    }
  }
  
  &__subtitle {
    font-size: 1.25rem;
    opacity: 0.9;
    margin-bottom: 2rem;
  }
  
  &__cta {
    display: inline-flex;
    gap: 1rem;
    margin-top: 1rem;
  }
}

// Card component
.feature-card {
  background: white;
  border-radius: 0.75rem;
  padding: 2rem;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05);
  transition: all 0.3s ease;
  
  &:hover {
    transform: translateY(-4px);
    box-shadow: 0 12px 25px rgba(0, 0, 0, 0.1);
  }
  
  &__icon {
    width: 4rem;
    height: 4rem;
    background: var(--brand-primary);
    border-radius: 50%;
    display: flex;
    align-items: center;
    justify-content: center;
    margin-bottom: 1.5rem;
    
    svg {
      width: 2rem;
      height: 2rem;
      fill: white;
    }
  }
  
  &__title {
    font-size: 1.25rem;
    font-weight: 600;
    margin-bottom: 0.75rem;
  }
  
  &__description {
    color: var(--color-text-muted);
    line-height: 1.6;
  }
}

Brand Integration

Brand Configuration

// Brand system
$brand-colors: (
  primary: #your-primary-color,
  secondary: #your-secondary-color,
  accent: #your-accent-color
);

$brand-fonts: (
  heading: 'Your-Brand-Font',
  body: 'Your-Body-Font',
  mono: 'Your-Mono-Font'
);

// Logo integration
.site-logo {
  height: 2.5rem;
  width: auto;
  
  @media (max-width: 768px) {
    height: 2rem;
  }
}

// Brand-consistent spacing
$brand-spacing: (
  xs: 0.25rem,
  sm: 0.5rem,
  md: 1rem,
  lg: 1.5rem,
  xl: 2rem,
  xxl: 3rem
);

Style Guide Implementation

// Style guide components
.style-guide {
  &__color-swatch {
    width: 100px;
    height: 100px;
    border-radius: 0.5rem;
    display: flex;
    align-items: center;
    justify-content: center;
    color: white;
    font-weight: 600;
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
  }
  
  &__typography-sample {
    margin-bottom: 2rem;
    
    h1, h2, h3, h4, h5, h6 {
      margin-bottom: 0.5rem;
    }
  }
}

Performance Considerations

CSS Optimization

// Efficient CSS practices
.component {
  // Use efficient selectors
  &__element {
    // Avoid deep nesting
  }
  
  // Use CSS custom properties for theming
  background-color: var(--component-bg, #ffffff);
  color: var(--component-text, #333333);
}

// Minimize unused CSS
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

// Only import needed components
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/utilities";

Loading Optimization

format:
  html:
    theme: cosmo
    css: 
      - href: styles.css
        preload: true
    include-in-header: |
      <link rel="preconnect" href="https://fonts.googleapis.com">
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

Best Practices

1. Design System Approach

  • Consistency: Use a consistent color palette and typography
  • Modularity: Create reusable component styles
  • Documentation: Document your design decisions
  • Accessibility: Ensure sufficient color contrast and readability

2. Performance

  • Minimize CSS: Only include necessary styles
  • Optimize Images: Use appropriate formats and sizes
  • Font Loading: Use font-display: swap for better performance
  • Critical CSS: Inline critical styles for faster rendering

3. Maintainability

  • Variables: Use CSS custom properties or SCSS variables
  • Organization: Structure CSS with clear naming conventions
  • Comments: Document complex styles and calculations
  • Version Control: Track changes to design system

4. Responsive Design

  • Mobile First: Design for mobile devices first
  • Progressive Enhancement: Add features for larger screens
  • Touch Targets: Ensure interactive elements are appropriately sized
  • Content Priority: Prioritize important content on smaller screens

5. Accessibility

  • Color Contrast: Maintain WCAG AA standards (4.5:1 ratio)
  • Focus States: Provide clear focus indicators
  • Screen Readers: Use semantic HTML and ARIA labels
  • Motion: Respect prefers-reduced-motion settings

Resources


This comprehensive guide covers all aspects of Quarto theming and styling, from basic theme selection to advanced custom component creation. Use these techniques to create professional, branded documentation that reflects your organization’s visual identity.