#Theming

selfdoc ships with two built-in themes and a comprehensive set of CSS custom properties that you can override without touching theme internals. Dark mode, high contrast, and print stylesheets work out of the box.

#Choosing a Theme

Set the theme field in your selfdoc.json configuration to select which built-in theme to use for your documentation site. The theme controls colors, typography, layout, and component styling. If omitted, the minimal theme is used by default:

{
  "theme": "minimal"
}

Two themes are available:

• minimal (default) -- GitHub-inspired styling with Inter and JetBrains Mono fonts. Blue accent color (#0969da), light sidebar background, dark topbar. Content-focused and familiar.
• clean -- Stripe-inspired styling with system fonts and a purple accent (#5046e4). White topbar, borderless code blocks, slightly taller line height (1.7 vs 1.6). Feels more polished and modern.

Both themes include full dark mode, high contrast, reduced motion, and print support.

#CSS Custom Properties

Every visual aspect of a selfdoc site is controlled by CSS custom properties defined in :root. Override any of them in a custom.css file (see next section) to change colors, fonts, or spacing without forking the theme.

#Colors

#Sidebar

#Topbar

#Code

#Components

#Typography

#Layout (clean only)

The clean theme defines two extra CSS custom properties not present in the minimal theme, controlling shadow depth and border radius for a more polished, card-like appearance. The minimal theme accesses these via CSS fallback syntax so they can still be overridden in custom.css:

Minimal uses these via CSS fallbacks (e.g., var(--radius, 4px)) so they can still be overridden in custom.css for either theme.

#Custom Styles

Create a docs/custom.css file in your project to override any CSS custom property or add your own styling rules. selfdoc automatically detects this file during build and injects it after the theme stylesheet, so your rules take precedence over the built-in theme values.

Example -- change the accent color and body font:

:root {
    --link: #e63946;
    --link-hover: #c1121f;
    --sidebar-active: #e63946;
    --badge-bg: #e63946;
    --font-body: 'IBM Plex Sans', system-ui, sans-serif;
}

No build configuration is needed. Just save the file and run selfdoc build.

#Dark Mode

Both themes ship with a complete dark color palette that covers every CSS custom property, ensuring consistent contrast and readability across all page elements including code blocks, tables, and admonitions. Dark mode activates in two ways:

1. Automatic -- the prefers-color-scheme: dark media query matches the user's OS setting. This is the default behavior with no configuration needed.
2. Manual toggle -- clicking the theme toggle button in the topbar sets data-theme="dark" (or "light") on the root element, overriding the OS preference.

#How the selectors work

The theme CSS uses a layered selector strategy with two complementary rules that handle both automatic OS-preference detection via the prefers-color-scheme media query and explicit user toggle interactions via the data-theme attribute on the root element:

• @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { ... } } -- applies dark colors when the OS prefers dark, unless the user has explicitly toggled to light.
• [data-theme="dark"] { ... } -- applies dark colors unconditionally when the toggle is set to dark, regardless of OS preference.

#Overriding dark mode colors

To customize dark mode colors in your custom.css file, you must mirror the same dual-selector pattern used by the built-in themes so that your overrides apply in both automatic and manual dark mode:

/* Override dark mode accent */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --link: #ff6b6b;
        --sidebar-active: #ff6b6b;
    }
}
[data-theme="dark"] {
    --link: #ff6b6b;
    --sidebar-active: #ff6b6b;
}

#Dark mode property values

The following table shows selected dark mode defaults for both the minimal and clean themes, useful as a reference when deciding which CSS custom properties to override in your custom.css dark mode rules:

#High Contrast

Both themes respond to the prefers-contrast: more media query for users who need stronger visual contrast between text, borders, and backgrounds. This is a browser or OS-level accessibility setting that requires no configuration on your part.

In light mode, high contrast overrides strengthen text and borders:

In dark mode with high contrast, the overrides flip to maximum brightness:

To override high contrast values in custom.css, nest your rules in the matching media query:

@media (prefers-contrast: more) {
    :root {
        --link: #0000cc;
    }
}

#Design Tool

The demo/index.html file is a standalone design tool for visually experimenting with theme settings without modifying any project files. Open it in a browser to see a full documentation page with an interactive settings panel that updates in real time.

Click the gear icon in the topbar to open the panel. It provides 16 knobs organized by category:

• Layout -- sidebar position (left/right/hidden), sidebar width, TOC position (right/inline), content width
• Typography -- font kind (sans/serif/mono/system), font size, heading transform (none/uppercase/small-caps), heading separator (none/line/dots)
• Spacing -- density (compact/default/relaxed)
• Colors -- light/dark mode, accent color, topbar color, gradient strip (on/off)
• Components -- border radius, code block style (default/minimal/bordered), table style (default/striped/bordered)

#Exporting settings

After adjusting the design knobs to your liking, click Copy CSS to clipboard to export your changes. The tool generates a custom.css snippet containing only the CSS custom properties you modified, ready to paste into your project's docs/custom.css file.

You can also click Copy link to get a URL that encodes all current settings, making it easy to share a design with collaborators.

#Print Stylesheet

Both themes include a comprehensive @media print block that produces clean, readable printed output suitable for PDF export. The layout switches to single-column with no max-width constraint, and all interactive and navigation elements are hidden when printing:

• Sidebar, table of contents, mobile TOC
• Topbar and hamburger menu
• Navigation links (previous/next), breadcrumbs
• Search dialog and triggers
• Copy/run buttons on code blocks
• Theme toggle, feedback widget, edit links
• Hero section, feature grid, reading progress bar
• Site footer

The layout switches to single-column with no max-width constraint. Colors reset to the light-mode palette for legibility on paper. Page breaks are avoided inside code blocks, tables, images, API entries, admonitions, and blockquotes.

To add custom print rules in custom.css:

@media print {
    :root {
        --text: #000;
    }
    .my-custom-element {
        display: none !important;
    }
}