> ## 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.

# Themes

Choose from 11 built-in themes or customize the visual style of your HolyDocs documentation site.

## Overview

HolyDocs ships with 11 built-in themes that control the overall visual style of your documentation — sidebar layout, card styles, header appearance, border radius, and content width. Set your theme in `docs.json`:

```json
{
  "theme": "holy"
}
```

## Available Themes

**Mint**

The default theme. Clean sidebar, transparent header, bordered cards, rounded code blocks. A balanced, modern look.
  **Maple**

Tinted sidebar with solid header. Elevated cards with shadows. Sharp code blocks for a professional feel.
  **Palm**

Dark sidebar with solid header. Filled cards and rounded code blocks. Bold and high-contrast.
  **Willow**

Minimal sidebar with transparent header. Ghost cards and inline code style. Light and airy.
  **Linden**

Clean sidebar with bordered header. Bordered cards and sharp code. Structured and editorial.
  **Almond**

Warm sidebar with transparent header. Soft cards and rounded code. Cozy and approachable.
  **Aspen**

Compact sidebar with solid header. Bordered cards with sharp code. Wide content area for technical docs.
  **Holy**

The signature HolyDocs theme. Dark sidebar, amber accent (#FBBF24), warm white light mode, pure black dark mode. Digital manuscript aesthetic.
  **Atlas**

Wide content area with a tinted sidebar and solid header. Elevated cards with generous padding. Designed for large-scale technical documentation and reference sites.
  **Nova**

Vibrant and modern. Gradient-tinted sidebar with transparent header. Filled cards with rounded corners. Best suited for product-forward documentation with strong brand presence.
  **Cipher**

Monospace-inspired and technical. Compact sidebar with bordered header. Ghost cards and sharp code blocks. Built for developer tools, CLIs, and security-focused projects.

## Theme Properties

Each theme defines the following layout and style properties:

| Property | Description | Example Values |
|---|---|---|
| `sidebarWidth` | Width of the left navigation sidebar | `240px` - `300px` |
| `contentMaxWidth` | Maximum width of the main content area | `680px` - `900px` |
| `rightSidebarWidth` | Width of the table-of-contents sidebar | `240px` - `260px` |
| `radius` | Border radius for cards, buttons, and inputs | `4px` - `12px` |
| `sidebarStyle` | Visual style of the sidebar | `clean`, `tinted`, `dark`, `minimal`, `warm`, `compact` |
| `headerStyle` | Style of the top navigation header | `transparent`, `solid`, `bordered` |
| `cardStyle` | Default card appearance | `bordered`, `elevated`, `filled`, `ghost`, `soft` |
| `codeStyle` | Code block corner style | `rounded`, `sharp`, `inline` |

## Theme Comparison

| Theme | Sidebar | Header | Cards | Radius | Content Width |
|---|---|---|---|---|---|
| Mint | Clean | Transparent | Bordered | 8px | 768px |
| Maple | Tinted | Solid | Elevated | 4px | 720px |
| Palm | Dark | Solid | Filled | 12px | 820px |
| Willow | Minimal | Transparent | Ghost | 6px | 680px |
| Linden | Clean | Bordered | Bordered | 4px | 800px |
| Almond | Warm | Transparent | Soft | 10px | 740px |
| Aspen | Compact | Solid | Bordered | 6px | 900px |
| Holy | Dark | Solid | Bordered | 2px | 780px |
| Atlas | Tinted | Solid | Elevated | 8px | 900px |
| Nova | Gradient | Transparent | Filled | 12px | 820px |
| Cipher | Compact | Bordered | Ghost | 2px | 860px |

## Colors

Customize the primary color and background colors independently of the theme:

```json
{
  "colors": {
    "primary": "#FBBF24",
    "light": "#FCD34D",
    "dark": "#D97706"
  }
}
```

### Background Colors

Override the default background for light and dark modes:

```json
{
  "colors": {
    "primary": "#007AFF",
    "background": {
      "light": "#F7F7F5",
      "dark": "#000000"
    }
  }
}
```

The `primary` color must be a valid 6-digit hex code (e.g., `#007AFF`). The `light` and `dark` color overrides are optional and fall back to theme defaults.

## Fonts

Customize heading and body fonts:

```json
{
  "fonts": {
    "heading": {
      "family": "Geist",
      "weight": "600",
      "source": "https://fonts.googleapis.com/css2?family=Geist:wght@600"
    },
    "body": {
      "family": "Inter",
      "weight": "400",
      "source": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600"
    }
  }
}
```

## Styling Options

Fine-tune additional style options:

```json
{
  "styling": {
    "eyebrows": "section",
    "latex": false,
    "codeblocks": "system"
  }
}
```

| Option | Values | Description |
|---|---|---|
| `eyebrows` | `section` \| `breadcrumbs` | Text shown above the page title |
| `latex` | `true` \| `false` | Enable LaTeX/math rendering |
| `codeblocks` | `system` \| `dark` | Code block theme follows system or always dark |

## Choosing a Theme

Not sure which theme to pick? Here is a guide based on common documentation types:

| Documentation Type | Recommended Themes | Why |
|---|---|---|
| **API Reference** | Aspen, Atlas, Cipher | Wide content area for code examples and endpoint tables |
| **Product Docs** | Mint, Palm, Nova | Balanced layout with strong visual identity |
| **Open Source** | Willow, Linden, Mint | Clean and approachable, low visual overhead |
| **Enterprise / Internal** | Holy, Maple, Linden | Professional and structured, editorial feel |
| **Developer Tools / CLI** | Cipher, Aspen, Holy | Monospace-friendly, code-focused layouts |
| **Marketing / DevRel** | Nova, Palm, Almond | Warm, branded, visually engaging |

You can change your theme at any time without affecting your content. Themes only control visual presentation — navigation structure, page content, and features remain unchanged.

## Theme + Color Combinations

Here are some popular theme and color pairings used by HolyDocs projects:

**Holy + Amber (the HolyDocs default)**

```json
    {
      "theme": "holy",
      "colors": {
        "primary": "#FBBF24",
        "light": "#FCD34D",
        "dark": "#D97706",
        "background": { "light": "#FFFBF0", "dark": "#000000" }
      }
    }
    ```
    Dark sidebar with warm amber accents. The signature HolyDocs look — digital manuscript meets modern tooling.
  **Mint + Blue (clean and classic)**

```json
    {
      "theme": "mint",
      "colors": {
        "primary": "#007AFF",
        "light": "#3395FF",
        "dark": "#0055CC"
      }
    }
    ```
    A safe, professional default. Works well for API documentation and technical guides where readability is the priority.
  **Nova + Purple (vibrant and modern)**

```json
    {
      "theme": "nova",
      "colors": {
        "primary": "#8B5CF6",
        "light": "#A78BFA",
        "dark": "#6D28D9",
        "background": { "light": "#FAFAFE", "dark": "#0A0A0F" }
      }
    }
    ```
    A bold, product-forward look with gradient sidebar tinting. Great for developer platforms and SaaS products.
  **Cipher + Green (terminal-inspired)**

```json
    {
      "theme": "cipher",
      "colors": {
        "primary": "#10B981",
        "light": "#34D399",
        "dark": "#059669"
      }
    }
    ```
    Monospace aesthetic with terminal-green accents. Ideal for CLI tools, security products, and infrastructure documentation.
  **Almond + Rose (warm and inviting)**

```json
    {
      "theme": "almond",
      "colors": {
        "primary": "#F43F5E",
        "light": "#FB7185",
        "dark": "#E11D48",
        "background": { "light": "#FFF7F5", "dark": "#1A0A0A" }
      }
    }
    ```
    Cozy and approachable. Works beautifully for consumer-facing products, design tools, and creative platforms.
  **Atlas + Teal (expansive and technical)**

```json
    {
      "theme": "atlas",
      "colors": {
        "primary": "#14B8A6",
        "light": "#2DD4BF",
        "dark": "#0D9488"
      }
    }
    ```
    Wide layout with teal accents. Excellent for large documentation sets with deep navigation hierarchies and extensive reference material.

## Theme Properties (Complete Reference)

Each theme defines a full set of visual tokens. Here is the complete property list:

| Property | Description | Values |
|---|---|---|
| `sidebarWidth` | Width of the left navigation sidebar | `220px` - `300px` |
| `contentMaxWidth` | Maximum width of the main content area | `680px` - `900px` |
| `rightSidebarWidth` | Width of the table-of-contents sidebar | `220px` - `260px` |
| `radius` | Border radius for cards, buttons, and inputs | `2px` - `12px` |
| `sidebarStyle` | Visual style of the sidebar | `clean`, `tinted`, `dark`, `minimal`, `warm`, `compact`, `gradient` |
| `headerStyle` | Style of the top navigation header | `transparent`, `solid`, `bordered` |
| `cardStyle` | Default card appearance | `bordered`, `elevated`, `filled`, `ghost`, `soft` |
| `codeStyle` | Code block corner style | `rounded`, `sharp`, `inline` |
| `sidebarDivider` | Whether the sidebar has a visible divider line | `true`, `false` |
| `headerShadow` | Whether the header casts a shadow on scroll | `true`, `false` |
| `contentPadding` | Horizontal padding around the content area | `24px` - `48px` |
| `tocStyle` | Table of contents visual treatment | `default`, `minimal`, `highlighted` |