Themes Overview

The theming system provides a modular, customizable way to style your documentation site. Themes control colors, typography, spacing, and other visual elements.

How Themes Work

┌─────────────────────────────────────────────────────────────────────────────┐
│                         THEME LOADING FLOW                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   site.yaml                                                                 │
│   theme: "@theme/minimal"                                                   │
│        │                                                                    │
│        ▼                                                                    │
│   ┌──────────────────────────────────────┐                                  │
│   │   Theme Resolver                     │                                  │
│   │   1. Resolve @theme alias            │                                  │
│   │   2. Load theme.yaml manifest        │                                  │
│   │   3. Check extends (inheritance)     │                                  │
│   │   4. Load CSS files                  │                                  │
│   │   5. Validate theme                  │                                  │
│   └──────────────────────────────────────┘                                  │
│        │                                                                    │
│        ▼                                                                    │
│   ┌──────────────────────────────────────┐                                  │
│   │   BaseLayout.astro                   │                                  │
│   │   Injects theme CSS in <head>        │                                  │
│   └──────────────────────────────────────┘                                  │
│        │                                                                    │
│        ▼                                                                    │
│   ┌──────────────────────────────────────┐                                  │
│   │   Page renders with theme styles     │                                  │
│   └──────────────────────────────────────┘                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Default vs Custom Themes

Type Location Alias
Default (built-in) src/styles/ @theme/default
Custom THEMES_DIR/theme-name/ @theme/theme-name

Default Theme

The built-in theme located in src/styles/. Always available and serves as the base for custom themes.

Custom Themes

User-created themes in the themes directory (configured via THEMES_DIR in .env). Can extend the default theme or be standalone.

Quick Start

Using the Default Theme

No configuration needed - the default theme is used automatically.

# site.yaml
site:
  name: "My Docs"
  # theme not specified = @theme/default

Using a Custom Theme

# site.yaml
site:
  name: "My Docs"

theme: "@theme/minimal"  # Use the "minimal" theme

Creating a Simple Theme

  1. Create theme directory:
dynamic_data/themes/my-theme/
├── theme.yaml
├── color.css
└── index.css
  1. Create manifest (theme.yaml):
name: "My Theme"
version: "1.0.0"
extends: "@theme/default"
supports_dark_mode: true
files:
  - color.css
  - index.css
  1. Override colors (color.css):
:root {
  --color-brand-primary: #8b5cf6;
  --color-brand-secondary: #7c3aed;
}

[data-theme="dark"] {
  --color-brand-primary: #a78bfa;
  --color-brand-secondary: #8b5cf6;
}
  1. Import in index.css:
@import './color.css';
  1. Use in site.yaml:
theme: "@theme/my-theme"

Theme Structure

Every theme consists of:

theme-name/
├── theme.yaml     # Required: Theme manifest
├── color.css      # Colors (light/dark mode)
├── font.css       # Typography
├── element.css    # Spacing, borders, shadows
├── markdown.css   # Content rendering
└── index.css      # Main entry point

See Theme Structure for details.

Theme Inheritance

Themes can extend other themes, only overriding specific values:

# theme.yaml
name: "Corporate Blue"
extends: "@theme/default"  # Inherit from default
files:
  - color.css  # Only override colors

This loads default theme CSS first, then applies your overrides.

See Theme Inheritance for details.

Dark Mode Support

Themes can support both light and dark modes:

/* Light mode (default) */
:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #212529;
}

/* Dark mode */
[data-theme="dark"] {
  --color-bg-primary: #1a1a2e;
  --color-text-primary: #eaeaea;
}

The [data-theme="dark"] selector is applied to <html> when dark mode is active.

CSS Variables

Themes work by defining CSS custom properties (variables). All layouts, components, and custom tags MUST use these variables instead of hardcoded values. This is a strict requirement - see Theme Compliance Rules for details.

Color Variables

--color-bg-primary      /* Main background */
--color-text-primary    /* Main text */
--color-brand-primary   /* Links, buttons */

Font Variables

--font-family-base      /* Body text */
--font-family-mono      /* Code */
--font-size-base        /* Default size */

Element Variables

--spacing-md            /* Standard spacing */
--border-radius-md      /* Rounded corners */
--shadow-md             /* Box shadows */

See CSS Variables Reference for the complete list.

Validation

Themes are validated at load time. The dev toolbar shows any errors:

  • Missing required files
  • Missing CSS variables
  • Invalid manifest format

See Theme Validation for details.

Next Steps