Mintlify best practices

Always consult mintlify.com/docs for components, configuration, and latest features.

If you are not already connected to the Mintlify MCP server, https://mintlify.com/docs/mcp, add it so that you can search more efficiently.

Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the docs.json file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.

Full schema at mintlify.com/docs.json.

Quick reference

CLI commands

• npm i -g mint

• Install the Mintlify CLI

• mint dev

• Local preview at localhost:3000

• mint broken-links

• Check internal links

• mint a11y

• Check for accessibility issues in content

• mint rename

• Rename/move files and update references

• mint validate

• Validate documentation builds

Required files

• docs.json

• Site configuration (navigation, theme, integrations, etc.). See global settings for all options.

• *.mdx files - Documentation pages with YAML frontmatter

Example file structure

project/ ├── docs.json # Site configuration ├── introduction.mdx ├── quickstart.mdx ├── guides/ │ └── example.mdx ├── openapi.yml # API specification ├── images/ # Static assets │ └── example.png └── snippets/ # Reusable components └── component.jsx

Organize content

When a user asks about anything related to site-wide configurations, start by understanding the global settings. See if a setting in the docs.json file can be updated to achieve what the user wants.

Navigation

The navigation property in docs.json controls site structure. Choose one primary pattern at the root level, then nest others within it.

Choose your primary pattern:

Pattern When to use

Groups Default. Single audience, straightforward hierarchy

Tabs Distinct sections with different audiences (Guides vs API Reference) or content types

Anchors Want persistent section links at sidebar top. Good for separating docs from external resources

Dropdowns Multiple doc sections users switch between, but not distinct enough for tabs

Products Multi-product company with separate documentation per product

Versions Maintaining docs for multiple API/product versions simultaneously

Languages Localized content

Within your primary pattern:

• Groups - Organize related pages. Can nest groups within groups, but keep hierarchy shallow

• Menus - Add dropdown navigation within tabs for quick jumps to specific pages

• expanded: false

• Collapse nested groups by default. Use for reference sections users browse selectively

• openapi

• Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit

Common combinations:

• Tabs containing groups (most common for docs with API reference)

• Products containing tabs (multi-product SaaS)

• Versions containing tabs (versioned API docs)

• Anchors containing groups (simple docs with external resource links)

Links and paths

• Internal links: Root-relative, no extension: /getting-started/quickstart

• Images: Store in /images , reference as /images/example.png

• External links: Use full URLs, they open in new tabs automatically

Customize docs sites

What to customize where:

• Brand colors, fonts, logo → docs.json . See global settings

• Component styling, layout tweaks → custom.css at project root

• Dark mode → Enabled by default. Only disable with "appearance": "light" in docs.json if brand requires it

Start with docs.json . Only add custom.css when you need styling that config doesn't support.

Write content

Components

The components overview organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component.

Common decision points:

Need Use

Hide optional details <Accordion>

Long code examples <Expandable>

User chooses one option <Tabs>

Linked navigation cards <Card> in <Columns>

Sequential instructions <Steps>

Code in multiple languages <CodeGroup>

API parameters <ParamField>

API response fields <ResponseField>

Callouts by severity:

• <Note>

• Supplementary info, safe to skip

• <Info>

• Helpful context such as permissions

• <Tip>

• Recommendations or best practices

• <Warning>

• Potentially destructive actions

• <Check>

• Success confirmation

Reusable content

When to use snippets:

• Exact content appears on more than one page

• Complex components you want to maintain in one place

• Shared content across teams/repos

When NOT to use snippets:

• Slight variations needed per page (leads to complex props)

Import snippets with import { Component } from "/path/to/snippet-name.jsx" .

Document APIs

Choose your approach:

• Have an OpenAPI spec? → Add to docs.json with "openapi": ["openapi.yaml"] . Pages auto-generate. Reference in navigation as GET /endpoint

• No spec? → Write endpoints manually with api: "POST /users" in frontmatter. More work but full control

• Hybrid → Use OpenAPI for most endpoints, manual pages for complex workflows

Encourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option.

Deploy

Mintlify deploys automatically when changes are pushed to the connected Git repository.

What agents can configure:

• Redirects → Add to docs.json with "redirects": [{"source": "/old", "destination": "/new"}]

• SEO indexing → Control with "seo": {"indexing": "all"} to include hidden pages in search

Requires dashboard setup (human task):

• Custom domains and subdomains

• Preview deployment settings

• DNS configuration

For /docs subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See /docs subpath.

Edge cases

Migrations

If a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the @mintlify/scraping CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components.

Hidden pages

Any page that is not included in the docs.json navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation.

Exclude pages

The .mintignore file is used to exclude files from a documentation repository from being processed.

Common gotchas

• Component imports - JSX components need explicit import, MDX components don't

• Frontmatter required - Every MDX file needs title at minimum

• Code block language - Always specify language identifier

• Never use mint.json

• mint.json is deprecated. Only ever use docs.json

Resources

• Documentation

• Configuration schema

• Feature requests

• Bugs and feedback