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

mintlify