Custom scripts

Use CSS to style HTML elements or add custom CSS and JavaScript to fully customize the look and feel of your documentation.

Style with Tailwind CSS

Use Tailwind CSS v3 to style HTML elements and components. You can control layout, spacing, colors, and other visual properties. Some common classes are:

• w-full - Full width
• aspect-video - 16:9 aspect ratio
• rounded-xl - Large rounded corners
• block, hidden - Display control
• dark:hidden, dark:block - Dark mode visibility

Style components with className

Components accept a className prop. Mintlify merges your classes with the component’s own styles, so you can restyle a single instance without wrapping it in extra markup or writing a CSS override.

<Note className="mt-0">This callout has no top margin.</Note>

<Card title="Quickstart" href="/quickstart" className="border-2 border-blue-500">
  Deploy your first documentation site.
</Card>

Three components do not accept className: Banner, MDX, and Visibility.

Arbitrary values and variants

Use arbitrary values when no utility class covers the value that you need.

<img src="/images/diagram.png" alt="System architecture diagram" className="w-[450px]" />

<Frame className="lg:w-[calc(100%-2rem)] bg-[#0f172a]">
  <img src="/images/hero.png" alt="Product hero image" />
</Frame>

Variants work as they do in any Tailwind project, including responsive prefixes (sm:, md:, lg:), state variants (hover:, focus:), dark:, data attribute variants (data-[state=open]:), opacity modifiers (bg-black/50), and the ! important modifier.

Mintlify generates CSS for the Tailwind classes that it finds in your page source, so write class names out in full.

{/* Generates CSS: the full class name appears in the page source. */}
<div className="bg-blue-500" />

{/* Generates no CSS: the class name is assembled at runtime. */}
<div className={`bg-${color}-500`} />

Add custom CSS

Mintlify includes any .css file inside your content directory on every page of your site. The content directory is the folder in your repository that contains your docs.json file and MDX pages. You do not need to import or reference the file from docs.json or your MDX files.

To add custom styles, create a .css file in your content directory. Any class names, ID selectors, or element selectors you define become available across all of your MDX files.

For example, define a class in style.css:

.my-callout {
  border-radius: 1rem;
  background: #f0f9ff;
  padding: 1rem;
}

You can combine custom class names with Tailwind CSS classes on the same element.

The references and styling of common elements are subject to change. Use custom styling with caution since breaking changes may occur in future updates.

For example, you can add the following style.css file to customize the styling of the navbar and footer.

#navbar {
  background: #fffff2;
  padding: 1rem;
}

footer {
  margin-top: 2rem;
}

Mintlify exposes two types of CSS targeting hooks:

• ID selectors: unique page-level elements targeted with #value { } in CSS
• Element selectors: component and layout elements targeted with value { } in CSS (no # or . prefix)

ID selectors

Each ID appears once per page. Use these as #value in CSS. For example, #navbar { background: red; }.

Element selectors

Multiple instances of these elements can appear on a page. Use these as value in CSS. For example, accordion { border: 1px solid red; }.

Custom JavaScript

Custom JavaScript lets you add custom executable code globally. It is the equivalent of adding a <script> tag with JavaScript code into every page.

Mintlify includes any .js file inside your content directory on every page of your site. Custom JavaScript files run after the page becomes interactive. You cannot scope them to specific pages. When you include multiple .js files, they run without a guaranteed order.

To load a third-party script, inject a <script> element from your custom JavaScript file instead of adding raw <script src="..."> tags in MDX:

const script = document.createElement('script');
script.src = 'https://example.com/widget.js';
script.async = true;
document.head.appendChild(script);

For example, you can add the following ga.js file to enable Google Analytics across your entire site.

window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');

Set API playground server variables

Use window.mintlify.api.playground.setServerVariables to prefill OpenAPI server variables from custom JavaScript. Use it when values become available after page load. For example, after authentication or a tenant change.

Pass an object of string values. Each call replaces the previous runtime values, which take precedence over OpenAPI defaults and saved values.

window.mintlify.api.playground.setServerVariables({
  tenantDomain: 'example.us.auth0.com',
});

To remove the runtime values, call:

window.mintlify.api.playground.clearServerVariables();

Calls made before the client initializes queue. Values apply to open and future playgrounds for the current page session and reset after a full-page refresh.

Access personalized user data

If your site uses authentication or personalization, custom scripts can read the identified visitor from window.mintlify.user. This is the same object exposed to MDX pages as the user variable, so it reflects the content field of your user data.

Because custom scripts run before user info resolves, listen for the mintlify:user event to identify when the user object is available. The event fires when user info resolves and again on any change. Its detail is the user object, or null when the visitor is signed out or unidentified.

window.addEventListener('mintlify:user', (event) => {
  const user = event.detail;
  if (!user) return; // Signed out or unidentified.

  renderAppLauncher(user);
});

If the user has already resolved by the time your script runs, read window.mintlify.user directly.

const user = window.mintlify?.user;
if (user) {
  renderAppLauncher(user);
}

window.mintlify.user is undefined until user info resolves and when the visitor is signed out or unidentified. Use optional chaining when reading nested fields.