#Dark Mode

ModernDuang includes a full dark mode implementation that respects your visitors' preferences while giving you control over the defaults. The theme uses CSS custom properties (variables) to switch between light and dark color schemes seamlessly.

#Configuration

Dark mode is configured under the dark_mode key in _config.modernduang.yml:

dark_mode:
  enable: true
  default: light

#How It Works

#Toggle Button

When enable: true, a sun/moon toggle button appears in the navigation bar. Visitors can click it to switch between light and dark modes. The toggle animates smoothly between the two states.

#Auto Detection

On the first visit (when no preference is saved), the theme checks the user's operating system preference via the prefers-color-scheme: dark CSS media query. If the visitor's OS is set to dark mode, the theme respects that — unless you have set default: light, in which case the theme preference takes priority.

The behavior is:

If you prefer to always defer to the visitor's OS setting, the default value serves as a fallback when the OS preference cannot be detected.

#localStorage Persistence

When a visitor manually toggles dark mode, their choice is saved to the browser's localStorage. On subsequent visits, the saved preference is loaded before the page renders, preventing a flash of incorrect theme. The saved preference also overrides any default or OS detection.

The storage key used is modernduang-theme with a value of 'light' or 'dark'.

#CSS Variables

ModernDuang implements dark mode entirely through CSS custom properties defined on the :root (light) and [data-theme="dark"] (dark) selectors. This approach means every component in the theme responds to theme changes automatically without JavaScript intervention per element.

Here are the primary CSS variables defined for light and dark modes:

#Light Mode (default :root)

#Dark Mode ([data-theme="dark"])

In addition to these, numerous component-specific variables adjust for dark mode — form inputs, table stripes, selection highlighting, scrollbar colors, and Mermaid diagram rendering.

#Disabling the Toggle

If you prefer to have only one color scheme, you can disable the toggle:

dark_mode:
  enable: false
  default: light

When disabled, the toggle button is hidden and the theme always renders in the default scheme. Visitors cannot change it.

#Dark Mode with Mermaid

Mermaid diagrams automatically adapt to dark mode. The theme injects the appropriate Mermaid theme (default or dark) based on the current color scheme. See the Mermaid Diagrams page for details.

#Best Practices

• Test both modes — Make sure your custom CSS, images, and content are legible in both themes
• Use semantic CSS variables — If you add custom styles, reference the theme variables (e.g., var(--text-primary)) rather than hardcoding colors
• Consider transparent images — PNGs with transparency work in both modes; white-background images may look like bright rectangles in dark mode

#Related Pages

• Custom Blockquotes — Blockquotes that adapt to the current color scheme via CSS variables
• Mermaid Diagrams — Diagram dark mode compatibility