mintlify
Build and maintain documentation sites with Mintlify. Use when
mintlify · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add FailproofAI/failproofai --skill mintlifyAbout this skill
name: mintlify description: Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references. license: MIT compatibility: Requires Node.js for CLI. Works with any Git-based workflow. metadata: author: mintlify version: "1.0" mintlify-proj: mintlify
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.
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:
- What pages exist and how they're organized
- What navigation groups are used (and their naming conventions)
- How the site navigation is structured
- What theme and configuration the site uses
Check for existing content
Search the docs before creating new pages. You may need to:
- Update an existing page instead of creating a new one
- Add a section to an existing page
- Link to existing content rather than duplicating
Read surrounding content
Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail.
Understand Mintlify components
Review the Mintlify components to select and use any relevant components for the documentation request that you are working on.
Quick reference
CLI commands
npm i -g mint- Install the Mintlify CLImint dev- Local preview at localhost:3000mint broken-links- Check internal linksmint a11y- Check for accessibility issues in contentmint validate- Validate documentation builds
Required files
docs.json- Site configuration (navigation, theme, integrations, etc.). See global settings for all options.*.mdxfiles - 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
Page frontmatter
Every page requires title in its frontmatter. Include description for SEO and navigation.
---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
---
Optional frontmatter fields:
sidebarTitle: Short title for sidebar navigation.icon: Lucide or Font Awesome icon name, URL, or file path.tag: Label next to the page title in the sidebar (for example, "NEW").mode: Page layout mode (default,wide,custom).keywords: Array of terms related to the page content for local search and SEO.- Any custom YAML fields for use with personalization or conditional content.
File conventions
- Match existing naming patterns in the directory
- If there are no existing files or inconsistent file naming patterns, use kebab-case:
getting-started.mdx,api-reference.mdx - Use root-relative paths without file extensions for internal links:
/getting-started/quickstart - Do not use relative paths (
../) or absolute URLs for internal pages - When you create a new page, add it to
docs.jsonnavigation or it won't appear in the sidebar
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 selectivelyopenapi- Auto-gener