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

# Custom CSS

Inject custom CSS into your HolyDocs site using CSS variables and style overrides.

## Overview

While HolyDocs themes cover most visual customization needs, you can inject custom CSS for fine-grained control over your documentation's appearance. Custom styles are applied after the theme styles, giving them higher specificity.

## CSS Variables

HolyDocs exposes CSS custom properties that you can override. These variables control colors, spacing, and typography across the entire site.

### Color Variables

```css
:root {
  --primary: #007AFF;
  --primary-light: #3395FF;
  --primary-dark: #0055CC;

  /* Page colors */
  --t-page: #FFFFFF;
  --t-ink: #1A1A1A;
  --t-heading: #111111;
  --t-body: #333333;
  --t-sub: #666666;
  --t-muted: #999999;
  --t-accent: #007AFF;

  /* Surface colors */
  --t-surface: #F9F9F9;
  --t-border: #E5E5E5;
  --t-hover: #F3F3F3;
}

[data-theme="dark"] {
  --t-page: #000000;
  --t-ink: #FFFFFF;
  --t-heading: #F5F5F5;
  --t-body: #CCCCCC;
  --t-sub: #999999;
  --t-muted: #666666;

  --t-surface: #111111;
  --t-border: #222222;
  --t-hover: #1A1A1A;
}
```

### Layout Variables

```css
:root {
  --sidebar-width: 280px;
  --content-max-width: 768px;
  --right-sidebar-width: 260px;
  --radius: 8px;
}
```

## Adding Custom CSS

Create a `custom.css` file in your docs directory and reference it in `docs.json`:

```
docs/
  docs.json
  custom.css
  introduction.mdx
```

Custom CSS file support requires a Pro plan or above. Free and Starter plans can use CSS variables through the theme configuration.

## Common Customizations

### Custom Sidebar Background

```css
.sidebar {
  background-color: #1A1A2E;
}

.sidebar .nav-link {
  color: #CCCCCC;
}

.sidebar .nav-link.active {
  color: #FBBF24;
  border-left-color: #FBBF24;
}
```

### Custom Card Styles

```css
.card {
  border: 1px solid var(--t-border);
  border-radius: 12px;
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.card:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
```

### Custom Code Block Theme

```css
.code-block {
  background-color: #0D1117;
  border: 1px solid #30363D;
  border-radius: 6px;
}

.code-block .code-header {
  background-color: #161B22;
  border-bottom: 1px solid #30363D;
}
```

### Custom Callout Colors

```css
.callout-warning {
  background-color: #FFF3CD;
  border-left-color: #FFC107;
}

.callout-tip {
  background-color: #D4EDDA;
  border-left-color: #28A745;
}
```

### Custom Header

```css
.header {
  backdrop-filter: blur(12px);
  background-color: rgba(255, 255, 255, 0.8);
  border-bottom: 1px solid var(--t-border);
}

[data-theme="dark"] .header {
  background-color: rgba(0, 0, 0, 0.8);
}
```

## Tailwind Utilities

HolyDocs includes approximately 150 Tailwind-compatible CSS utility classes for use in MDX content. These are commonly used for layout and spacing:

```mdx
<div className="flex items-center gap-4 mt-6">
  <img src="/images/logo.svg" className="h-12 w-12 rounded-full" />
  <span className="text-lg font-semibold">HolyDocs</span>
</div>
```

Supported utility categories:
- **Layout**: `flex`, `grid`, `block`, `inline`, `hidden`
- **Spacing**: `p-*`, `m-*`, `gap-*`
- **Sizing**: `w-*`, `h-*`, `max-w-*`
- **Typography**: `text-*`, `font-*`, `leading-*`
- **Borders**: `rounded-*`, `border-*`
- **Colors**: `bg-*`, `text-*`

When using className in MDX, the attribute is automatically converted to the HTML `class` attribute during rendering. Both `className` and `class` work in HolyDocs MDX files.

## Background Decoration

Add visual decoration to your docs background:

```json
{
  "background": {
    "decoration": "grid",
    "color": {
      "light": "#F7F7F5",
      "dark": "#000000"
    }
  }
}
```

Available decorations:
- `gradient` — Subtle gradient behind the header area
- `grid` — Light grid pattern overlay
- `windows` — Glassmorphism-style windows effect