> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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"
  }
}
```