Mintlify best practices

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

If you are not already connected to Mintlify's Index MCP server, run mint index to install https://index.mintlify.com/mcp. It supports Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf, and Zed. Follow the generated usage rules when using it.

Always favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.

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.

Before you write

Understand the project

Read docs.json in the project root. This file defines the entire site: navigation structure, theme, colors, links, API and specs.

Understanding the project tells you: