Building open documentation with Mintlify

Building documentation is not easy, and there are a lot of options but Mintlify proved the best given its ease of use and flexibility. But, despite its themes, accents and promise of customisation all via a docs.json file, it still falls short of creating something that can really become 'your' documentation. So, simply put, Mintlify gets you most of the way there out of the box but, not enough to actually make it identify with your brand, That's why we made this starter kit, and we made it open-source. Here is a brief explanation of that recently published repository that can enable you to make it yours - all via the style.css option - provided by Mintlify itself.

The core idea is simple:

A small set of design tokens in theme/tokens.css are defined
Those tokens are mapped into Mintlify’s internal variables in theme/mapping.css
Then they are applied uniformly and consistently across real Mintlify components in components.css

This keeps things predictable, maintainable, and easy to change later.

We do note that this is best for simple color pallettes such as our duotone branding but we hope more can contribute and add their own flair on top of our work, for all to use and build.

1. Why not one big file?

We chose to keep it modular and easier to maintain, especialyl given a lot of the rule use !important to override Mintlify defaults so that if any issues arise it can be found and isolated more quickly.

Our design, as mentioned, comes through in three ways:

`theme/tokens.css`

This is the design system layer.

It defines:

colors
surface tones
borders
typography
radii

You should be able to change the overall look and feel by editing only this file.

`theme/mapping.css`

This is the translation layer.

Mintlify uses variable names like --primary, --background, --muted, --border, and a large set of --tw-prose-* variables for typography.

This file maps your tokens onto Mintlify’s expected variables, as Mintlify components automatically inherit your design system. This is an abstraction so that you don't need to inspect any files or isolate radix buttons or icons manually.

`components.css`

This is the override layer.

Mintlify generates a lot of structure dynamically, so this file targets stable anchors like

#header, #navbar, #sidebar, #footer
[role="main"]
[data-component-part="..."]
menu, dialog, and mobile navigation surfaces

The goal is to style real components consistently, without manually hunting down individual elements.

2. Colours

Start in theme/tokens.css:

:root {
  --ot-bg: #faf3e0;
  --ot-fg: #36251e;
}

Those two variables define the entire background/foreground relationship of the docs. To invert the scheme for dark mode, you don’t need a second palette. Just flip them:

html.dark {
  --ot-bg: #36251e;
  --ot-fg: #faf3e0;
}

The rest of the color pallets and its variations stem from these two colors so no more hastle needed to make it yours, just how Mintlify works.

3. Border radius

As you may have seen, we like straight lines so conforming components to mimic our brand aeshtetic was essential. So, instead of hardcoding border radii on individual components, this setup uses three shared tokens (like Apple used to do):

:root {
  --ot-radius-xs: 15px;
  --ot-radius-sm: 15px;
  --ot-radius-md: 15px;
}

Cards, menus, callouts, buttons, and dialogs all reference these values. Change them once, and the entire UI updates.

4. Customisation

If you do want to make changes to any components that may have been missed, this can be handled in components.css.

Because everything is driven by shared tokens, these overrides stay small and readable, and they won’t break when you change colors, fonts, or radii later.

Images

Mintlify styling screenshot — An example using a blue background with white text, dark mode.

White background texture (vertical) — White background texture. A light mode example using inverse colors of example above.

Brown background texture — Brown background. Example of dark theme like our docs.

Summary

Our aim was simple, keep it easy and clean so that you only have to tweak 4 values or so without looking at anything under the hood and you can have docs that look like Coinbase's or Anthropic's pretty quickly. Check out example images below which can also be found in the link at the top of the page. If you are interested in making edits or offering possible ideas for improvement, by all means offer a PR and we will update the repo as soon as possible. For more information about our mission and our next steps, check our our roadmap and subscribe to our mailing list for regular summaries!