Custom CSS

Add custom CSS files to your documentation project to style any element beyond what the built-in theme exposes. Your stylesheets load after the default theme, so your rules take priority.

Prerequisites

You need publishing access and either a .css file in your project or an external HTTPS stylesheet URL.

Configure custom CSS from the Editor

Use the Editor when you want to add or update styles without editing documentation.json directly.

Configure custom CSS in documentation.json

Use documentation.json when you manage site configuration in version control or want stylesheet changes reviewed alongside other documentation updates.

{
  "css": [
    { "src": "styles/custom.css" },
    { "src": "https://cdn.example.com/external-styles.css" }
  ]
}

Each item in the css array supports one field:

• src (string, required) — Relative path to a .css file in your project, or an external HTTPS URL

File requirements

Follow these rules when adding a stylesheet:

• Files must use a .css extension
• Paths are relative to the project root, such as styles/brand.css
• Maximum file size is 5 MB
• The file must already exist in your documentation project before you reference it
• External URLs must use HTTPS

Component class names

Documentation.AI exposes stable dai-* class names on major layout regions, navigation elements, and MDX components. Use these selectors when you want precise styling without relying on generated or browser-inspected class names that may change.

Layout and structure

Navbar

Sidebar

Search and AI

Table of contents

MDX components

API playground

Other

CSS variables

Override built-in CSS custom properties when you want to adjust theme-driven colors without rewriting component selectors. These variables layer on top of the theme colors defined in documentation.json.

:root {
  --brand: #3143e3;
  --brand-text: #ffffff;
  --heading: #1a1a1a;
  --body: #374151;
  --navbar-bg: #ffffff;
  --sidebar-bg: #f9fafb;
  --content-bg: #ffffff;
  --footer-border: #e5e7eb;
  --toc-text: #6b7280;
  --toc-active-text: #3143e3;
}

.dark {
  --brand: #85a1ff;
  --brand-text: #000000;
  --heading: #f2f2f2;
  --body: #c1c1c1;
  --navbar-bg: #0f0f0f;
  --sidebar-bg: #111111;
  --content-bg: #0f0f0f;
  --footer-border: #262626;
  --toc-text: #9ca3af;
  --toc-active-text: #85a1ff;
}

Use the built-in theme color settings for your primary brand, heading, and body text colors whenever possible. CSS variables are most useful when you need more specific control over elements such as the navbar background, sidebar background, footer border, or table of contents colors.

Examples

Start with a small, targeted rule and verify it on a published page before expanding to broader overrides.

Change the sidebar background

.dai-sidebar {
  background-color: #f8fafc;
}

.dark .dai-sidebar {
  background-color: #0f172a;
}

Add custom navbar styling

.dai-navbar {
  border-bottom: 2px solid var(--brand);
  backdrop-filter: blur(12px);
}

Highlight the active table of contents item

.dai-toc-item-active {
  font-weight: 600;
  border-left: 3px solid var(--brand);
  padding-left: 8px;
}

Adjust callout body text

.dai-callout-body {
  font-size: 0.9rem;
  line-height: 1.6;
}

Loading order

Styles load in this order:

1. Built-in base styles for layout and components
2. Theme CSS variables from the documentation.json colors configuration
3. Custom CSS stylesheets from your css array, in the order listed

Because custom stylesheets load last, they can override earlier styles.

Security

• Local files are served from a secure CDN. Path traversal patterns such as ../ are rejected.
• External URLs should point to trusted sources only.

Troubleshooting

.dark .dai-sidebar {
  background-color: #0f172a;
}

What's next