Dark Mode
Configure dark mode behavior and customize the light and dark theme appearances in HolyDocs.
Overview
HolyDocs supports three appearance modes: system (follows OS preference), light, and dark. By default, the appearance follows the user's system preference and can be toggled with the theme switch in the header.
Configuration
Set the default appearance in docs.json:
json{ "appearance": { "default": "system", "strict": false }}
Appearance Options
| Option | Type | Default | Description |
|---|---|---|---|
default | system | light | dark | system | Initial appearance when a user first visits |
strict | boolean | false | When true, hides the theme toggle and locks to the default mode |
Examples
Always Light Mode
json{ "appearance": { "default": "light", "strict": true }}
Always Dark Mode
json{ "appearance": { "default": "dark", "strict": true }}
Follow System (Default)
json{ "appearance": { "default": "system", "strict": false }}
Custom Colors per Mode
Override background and surface colors for each mode:
json{ "colors": { "primary": "#FBBF24", "background": { "light": "#F7F7F5", "dark": "#000000" } }}
CSS Dark Mode Selectors
In custom CSS, target dark mode using the [data-theme="dark"] attribute:
css/* Light mode styles (default) */.custom-banner { background: linear-gradient(135deg, #F7F7F5, #FFFFFF); color: #1A1A1A;}/* Dark mode overrides */[data-theme="dark"] .custom-banner { background: linear-gradient(135deg, #111111, #000000); color: #F5F5F5;}
Image Handling
For images that need different versions in light and dark mode, use the <picture> element or provide both variants:
mdx<picture> <source media="(prefers-color-scheme: dark)" srcSet="/images/diagram-dark.png" /> <img src="/images/diagram-light.png" alt="Architecture diagram" /></picture>
Alternatively, use CSS to show/hide images based on theme:
mdx<img src="/images/diagram-light.png" alt="Architecture diagram" className="block dark:hidden" /><img src="/images/diagram-dark.png" alt="Architecture diagram" className="hidden dark:block" />
Logo Variants
Configure separate logos for light and dark modes in docs.json:
json{ "logo": { "light": "/images/logo-light.svg", "dark": "/images/logo-dark.svg" }}
HolyDocs automatically switches the logo based on the active theme. If you provide a single string instead of an object, the same logo is used for both modes.
Code Block Themes
Code blocks can follow the system appearance or use a fixed dark theme:
json{ "styling": { "codeblocks": "system" }}
| Value | Behavior |
|---|---|
system | Light code blocks in light mode, dark in dark mode |
dark | Always use dark code block background regardless of theme |
Most developer documentation sites use "codeblocks": "dark" because dark code blocks are easier to read and look consistent in both modes.
Theme Persistence
When a user toggles the theme, their preference is stored in localStorage under the key holydocs-theme. On subsequent visits, the stored preference is applied before the page renders to prevent a flash of incorrect theme.
Favicon per Mode
You can also provide separate favicons for light and dark mode:
json{ "favicon": { "light": "/images/favicon-light.svg", "dark": "/images/favicon-dark.svg" }}