Theming

Oxidoc is styled entirely with CSS custom properties (--oxidoc-* variables). Override any variable to customize your site — from a single color change to a complete visual redesign.

Quick Config

For simple changes, set values directly in oxidoc.toml:

oxidoc.tomltoml

[theme]
primary = "#8b5cf6"
accent = "#f59e0b"
font = "Inter, sans-serif"
code_font = "JetBrains Mono, monospace"
dark_mode = "system"

Field	What it controls
`primary`	Links, active sidebar items, buttons, callout info borders
`accent`	Accent highlights and decorative elements
`font`	Body text font stack
`code_font`	Code blocks and inline code font stack
`dark_mode`	`"system"` (default), `"light"`, or `"dark"`

These fields are convenience shortcuts. For full control, use custom CSS.

Dark Mode

The dark_mode setting controls initial behavior:

"system" — follows OS preference via prefers-color-scheme, with a toggle in the header
"light" — always light mode
"dark" — always dark mode

In system mode, users can toggle manually. The preference is stored in the browser.

Custom CSS

Load one or more CSS files that override any --oxidoc-* variable:

oxidoc.tomltoml

[theme]
custom_css = ["assets/variables.css", "assets/overrides.css"]

Files are concatenated in order. All Oxidoc styles are wrapped in @layer oxidoc, so your custom CSS always wins the cascade — no !important needed.

CSS Variable Reference

Every visual property in Oxidoc is controlled by a CSS variable. Override them in :root for light mode and [data-theme="dark"] for dark mode.

Core Colors

assets/custom.csscss

:root {
  --oxidoc-primary: #2563eb;
  --oxidoc-accent: #f59e0b;
  --oxidoc-bg: #ffffff;
  --oxidoc-bg-secondary: #f8fafc;
  --oxidoc-text: #1e293b;
  --oxidoc-text-secondary: #64748b;
  --oxidoc-border: #e2e8f0;
  --oxidoc-code-bg: #f1f5f9;
}

[data-theme="dark"] {
  --oxidoc-primary: #3b82f6;
  --oxidoc-accent: #fbbf24;
  --oxidoc-bg: #0f172a;
  --oxidoc-bg-secondary: #1e293b;
  --oxidoc-text: #e2e8f0;
  --oxidoc-text-secondary: #94a3b8;
  --oxidoc-border: #334155;
  --oxidoc-code-bg: #1e293b;
}

Primary Color Shades

Auto-generated from your primary color using color-mix():

:root {
  --oxidoc-primary-light    /* 70% primary + white */
  --oxidoc-primary-dark     /* 70% primary + black */
  --oxidoc-primary-lighter  /* 40% primary + white */
  --oxidoc-primary-darker   /* 40% primary + black */
}

These adapt automatically when you change --oxidoc-primary.

Semantic Colors

Used by callouts, badges, tags, API method badges, and status indicators:

assets/custom.csscss

:root {
  --oxidoc-success: #10b981;       --oxidoc-success-text: #059669;
  --oxidoc-warning: #f59e0b;       --oxidoc-warning-text: #b45309;
  --oxidoc-error: #ef4444;         --oxidoc-error-text: #dc2626;
  --oxidoc-info: #3b82f6;          --oxidoc-info-text: #2563eb;
  --oxidoc-new: #8b5cf6;           --oxidoc-new-text: #7c3aed;
  --oxidoc-deprecated: #6b7280;    --oxidoc-deprecated-text: #4b5563;
}

All semantic colors have dark mode variants applied automatically.

Utility Colors

assets/custom.csscss

:root {
  --oxidoc-text-muted: #6b7280;
  --oxidoc-bg-subtle: #f3f4f6;
  --oxidoc-on-primary: #fff;
  --oxidoc-shadow: rgba(0, 0, 0, 0.1);
  --oxidoc-overlay: rgba(0, 0, 0, 0.4);
}

Callout Customization

Each callout type exposes its own variables:

assets/custom.csscss

.oxidoc-callout-warning {
  --oxidoc-callout-color: #ea580c;
  --oxidoc-callout-bg: #fff7ed;
  --oxidoc-callout-border: #ea580c;
  --oxidoc-callout-text: #1e293b;
}

Typography

assets/custom.csscss

:root {
  --oxidoc-font-sans: system-ui, -apple-system, sans-serif;
  --oxidoc-font-mono: "SF Mono", "Fira Code", monospace;
}

Layout

assets/custom.csscss

:root {
  --oxidoc-content-max: 48rem;
  --oxidoc-sidebar-width: 16rem;
  --oxidoc-toc-width: 14rem;
  --oxidoc-header-height: 3.5rem;
}

Border Radius

assets/custom.csscss

:root {
  --oxidoc-radius-sm: 0.25rem;
  --oxidoc-radius-md: 0.375rem;
  --oxidoc-radius-lg: 0.5rem;
}

Shadows

assets/custom.csscss

:root {
  --oxidoc-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --oxidoc-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
  --oxidoc-shadow-lg: 0 12px 36px rgba(0, 0, 0, 0.15);
}

Z-Index

assets/custom.csscss

:root {
  --oxidoc-z-tooltip: 10;
  --oxidoc-z-back-to-top: 50;
  --oxidoc-z-sidebar: 90;
  --oxidoc-z-header: 100;
  --oxidoc-z-skip-nav: 200;
  --oxidoc-z-overlay: 1000;
}

Transitions

assets/custom.csscss

:root {
  --oxidoc-transition-fast: 0.15s ease;
  --oxidoc-transition-normal: 0.25s ease;
  --oxidoc-transition-slow: 0.4s ease;
  --oxidoc-transition-spring: 0.5s cubic-bezier(0.19, 1, 0.22, 1);
}

Community Themes

Community themes are .css files that override --oxidoc-* variables. To use one:

oxidoc.tomltoml

[theme]
custom_css = ["assets/dracula.css"]

To create a theme, write a CSS file that sets the variables above for both :root (light) and [data-theme="dark"] (dark), then share it.