Documentation Guides

Writing a Custom Theme #

This guide walks you through creating a custom theme for romero from scratch.

Theme Examples #

Here’s what’s possible with romero’s theming system. The built-in themes demonstrate different approaches:

Default Theme #

A dark-first design with indigo/violet accents on neutral grays.

Default theme

GitBook Theme #

Light-first design with warm stone tones and orange accent.

GitBook theme

WorkOS Theme #

Dark-first design with amber/gold accents on blue-tinted neutrals.

WorkOS theme

Overview #

Romero’s theming system is built on CSS custom properties (variables). Default values are defined in main.css, and your theme file only needs to override the variables you want to change.

Understanding the Architecture #

CSS Load Order #

CSS files are loaded in this order:

  1. Google Fonts - Inter (UI) and JetBrains Mono (code)
  2. bulma.min.css - Base CSS framework
  3. all.min.css - Font Awesome icons
  4. main.css - Core styling with default theme variables
  5. {theme}.css - Your theme overrides

Your theme file is loaded after main.css, so your CSS variables override the defaults.

Default Variables #

The following variables are defined in main.css with default (dark theme) values:

:root {
    /* Primary accent colors */
    --primary-3: 30 32 36;
    --primary-4: 35 38 43;
    --primary-7: 55 60 70;
    --primary-9: 99 102 241;
    --primary-10: 129 140 248;
    --primary-11: 165 180 252;

    /* Tint scale - backgrounds and text */
    --tint-1: 13 13 15;
    --tint-2: 18 18 21;
    --tint-3: 23 23 27;
    --tint-4: 28 28 33;
    --tint-5: 35 35 41;
    --tint-6: 45 45 52;
    --tint-9: 113 113 122;
    --tint-11: 161 161 170;
    --tint-12: 250 250 250;

    /* Code blocks */
    --code-bg: 22 22 26;
    --code-border: 45 45 52;

    /* Contrast color for text on primary-9 background */
    --contrast-primary-9: 255 255 255;
}

Step 1: Create the Theme Directory #

Create a templates/html/css/ directory in your book’s root (alongside book.toml):

mkdir -p templates/html/css

Step 2: Create Your Theme File #

Create templates/html/css/my-theme.css. You only need to override the variables you want to change:

/* My Custom Theme - Ocean Blue */
:root {
    /* Change accent to ocean blue */
    --primary-9: 56 189 248;
    --primary-10: 125 211 252;
    --primary-11: 186 230 253;

    /* Slightly warmer background */
    --tint-1: 15 23 30;
    --tint-2: 20 30 40;
}

That’s it! All other variables will use the defaults from main.css.

Full Theme Example #

For a complete theme with light/dark mode support:

/* My Custom Theme */

/* Dark mode overrides */
:root {
    --primary-9: 56 189 248;
    --primary-10: 125 211 252;
    --primary-11: 186 230 253;

    --tint-1: 15 23 30;
    --tint-2: 20 30 40;
    --tint-3: 28 38 50;
}

/* Light mode overrides */
:root[data-theme="light"] {
    --primary-9: 14 116 144;
    --primary-10: 6 182 212;
    --primary-11: 8 145 178;

    --tint-1: 255 255 255;
    --tint-2: 240 249 255;
    --tint-3: 224 242 254;
    --tint-12: 15 23 42;
}

Step 3: Enable Your Theme #

Via Configuration #

Add to book.toml:

[output.html]
theme = "my-theme"

Via Command Line #

romero build --theme my-theme
romero serve --theme my-theme

Step 4: Build and Test #

romero build

Or with live reloading:

romero serve

Test both light and dark modes using the theme toggle button.

CSS Variable Reference #

Primary Accent Colors #

Variable Purpose
--primary-3 Darkest accent shade
--primary-4 Dark accent (hover)
--primary-7 Medium accent (borders)
--primary-9 Main accent (links, active)
--primary-10 Bright accent (hover)
--primary-11 Lightest accent (inline code)

Tint Scale (Backgrounds & Text) #

Variable Purpose
--tint-1 Primary background
--tint-2 Secondary background (sidebar)
--tint-3 Tertiary background (cards)
--tint-4 Hover state
--tint-5 Borders
--tint-6 Strong borders
--tint-9 Muted text
--tint-11 Secondary text
--tint-12 Primary text

Code & Contrast #

Variable Purpose
--code-bg Code block background
--code-border Code block border
--contrast-primary-9 Text on --primary-9 background

Tips #

Color Format #

Colors use RGB space-separated format (56 189 248) not rgb(56, 189, 248). This allows romero to use them with opacity modifiers.

Minimal Themes #

Start small - override just --primary-9 and --tint-1 to see immediate results.

Contrast #

Ensure --tint-12 has good contrast against --tint-1 (7:1 ratio recommended).

Advanced: Custom Fonts #

@import url('https://fonts.googleapis.com/css2?family=Outfit&display=swap');

* {
    font-family: 'Outfit', sans-serif !important;
}

Advanced: Layout Overrides #

:root {
    --sidebar-width: 280px;
    --content-max-width: 800px;
}

Real-World Example: GitBook Theme #

Here’s a simplified version of the built-in GitBook theme showing a complete light-first design:

/* GitBook-inspired theme
 * Light-first with warm stone tones and orange accent
 *
 * Color source:
 *   Brand orange:   #fe551b  → 254 85 27
 *   Dark text:      #1c1917  → 28 25 23
 *   Background:     #ffffff  → 255 255 255
 */

/* Font overrides */
* {
    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

pre code, code {
    font-family: 'Geist Mono', 'JetBrains Mono', monospace !important;
}

/* Light theme - default */
:root {
    /* Primary accent — orange */
    --primary-3: 255 241 236;
    --primary-4: 255 224 213;
    --primary-7: 254 150 110;
    --primary-9: 254 85 27;
    --primary-10: 254 85 27;
    --primary-11: 220 65 10;

    /* Tint scale — warm stone palette */
    --tint-1: 255 255 255;
    --tint-2: 250 250 249;
    --tint-3: 245 245 244;
    --tint-4: 239 238 237;
    --tint-5: 231 229 228;
    --tint-6: 214 211 209;
    --tint-9: 121 113 107;
    --tint-11: 87 83 77;
    --tint-12: 28 25 23;

    --contrast-primary-9: 255 255 255;

    --code-bg: 250 250 249;
    --code-border: 239 238 237;
}

/* Dark mode variant */
:root[data-theme="dark"] {
    --primary-9: 254 110 55;
    --primary-10: 254 135 85;
    --primary-11: 255 170 130;

    --tint-1: 18 16 15;
    --tint-2: 24 22 20;
    --tint-3: 32 29 27;
    --tint-12: 245 245 244;

    --code-bg: 24 22 20;
    --code-border: 50 47 44;
}

This example shows: