Dark Mode¶
Lumina includes dark mode out of the box. Readers can toggle between light, dark, and system preference using the button in the header.
Configuration¶
Set the default color mode in your conf.py:
html_theme_options = {
"dark_mode_default": "auto", # "auto", "light", or "dark"
}
"auto"Follows the reader’s operating system preference. This is the default.
"light"Forces light mode regardless of system preference.
"dark"Forces dark mode regardless of system preference.
How It Works¶
Lumina toggles dark mode via the data-theme attribute on the <html> element:
Light mode:
<html data-theme="light">Dark mode:
<html data-theme="dark">
The reader’s choice is persisted in localStorage under the key lumina-theme. An inline script in the page <head> applies the theme before the first paint, preventing any flash of unstyled content (FOUC).
Customizing Dark Mode Colors¶
Override the dark mode color palette by targeting the [data-theme="dark"] selector in a custom stylesheet.
First, add the stylesheet to your project:
html_static_path = ["_static"]
html_css_files = ["custom.css"]
Then override the dark mode properties:
[data-theme="dark"] {
--lumina-bg: #09090b;
--lumina-bg-secondary: #18181b;
--lumina-text: #fafafa;
--lumina-text-muted: #a1a1aa;
--lumina-border: #27272a;
--lumina-accent: #10b981;
--lumina-accent-light: #022c22;
--lumina-code-bg: #1c1c20;
}
Tip
See Custom Styling for the full list of CSS custom properties including light mode colors and admonition colors.