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

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

Navigation

The

navigation

docs.json

Choose your primary pattern:

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

custom.css

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:

<Accordion>

<Expandable>

<Tabs>

<Card>

<Columns>

<Steps>

<CodeGroup>

<ParamField>

<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

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

Exclude pages

The

.mintignore

Common gotchas

1. Component imports - JSX components need explicit import, MDX components don't
2. Frontmatter required - Every MDX file needs

   title

   at minimum
3. Code block language - Always specify language identifier
4. Never use

   mint.json

   -

   mint.json

   is deprecated. Only ever use

   docs.json

Resources

• Documentation
• Configuration schema
• Feature requests
• Bugs and feedback