Custom scripts

Inject custom JavaScript and CSS into your Mintlify site for functionality not covered by built-in integrations.

For tools and behaviors not covered by Mintlify’s built-in integrations, you can inject custom scripts and styles into every page of your docs site.

Custom CSS

Create a style.css file at the root of your repository. Mintlify automatically loads it on every page. Use it to override default styles or add custom UI elements:

/* Adjust the sidebar width */
.sidebar {
  min-width: 280px;
}

/* Custom callout style */
.callout-custom {
  background: #f0f9ff;
  border-left: 4px solid #0ea5e9;
}

Reference style.css in docs.json to ensure it’s applied:

"styling": {
  "customCSS": "/style.css"
}

Custom JavaScript via Google Tag Manager

The cleanest way to inject arbitrary scripts is through Google Tag Manager. Add the GTM integration to docs.json:

"integrations": {
  "gtm": {
    "tagId": "GTM-XXXXXXX"
  }
}

Then manage all your custom scripts from the GTM dashboard. This keeps your repository clean and lets non-developers update scripts without code changes or deployments.

Common use cases

Use case	Recommended approach
A/B testing (Optimizely, VWO)	Google Tag Manager
Session recording (FullStory)	Built-in integration or GTM
Custom chat widget	GTM or built-in Intercom integration
Scroll depth tracking	GTM with a custom trigger
Banner or promotional overlay	Custom JavaScript via GTM

React components

For more complex UI requirements, Mintlify supports custom React components. Add a components/ directory to your repository and reference components in your MDX files. This is the right approach for reusable UI patterns that go beyond what CSS can do.

Custom React components require familiarity with MDX and React. Changes to component code trigger a full rebuild of your docs site.