Custom CSS

Add custom stylesheets to override default styles, target specific components, and fine-tune your site's visual design.

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.

Start with Colors & Typography for brand colors, headings, and text. Use custom CSS when you need layout tweaks, component-level styling, or overrides the theme settings don't cover.

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.

Open Site Config

In the Editor, click Site Config in the top toolbar.

Navigate to Custom CSS

Select Custom CSS from the left sidebar.

Add a stylesheet

Click Add Stylesheet and select a CSS file from your project. Only .css files appear in the picker.

You can also paste an external stylesheet URL instead of selecting a project file.

Publish

Click Publish to deploy the stylesheet to your live site.

After publishing, refresh your site and confirm the updated styles appear where you expect them.

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

CSS paths must be relative. Do not start paths with /, ./, or ../. Path traversal patterns are rejected for security.

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

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.

For dark mode overrides, scope variable changes or selector-based styles under .dark. That keeps your light and dark themes predictable and avoids unintended color combinations.

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

Styles are not applying

Dark mode styles are not working

Changes are not visible after editing

External stylesheet is not loading

What's next

Colors and typography Custom scripts Templates Site configuration