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

Tailwind CSS arbitrary values are not supported. For custom values, use the style prop instead.

<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />

Add custom CSS

Mintlify includes any .css file inside your content directory on every page of your site. 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 JS lets you add custom executable code globally. It is the equivalent of adding a <script> tag with JS 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');

Access authenticated user data

If your site uses authentication, custom scripts can read the signed-in user 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.

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

  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. Use optional chaining when reading nested fields.