---
name: ck-mintlify
description: Build and deploy Mintlify documentation sites. Use when creating API docs, developer portals, or knowledge bases with MDX components, OpenAPI integration, and multi-language navigation.
---

# Mintlify Documentation Builder

Transforms Markdown/MDX files into interactive documentation sites with themes, navigation, and AI features.

## When to Use

- Building API documentation or developer portals
- Setting up docs.json configuration and navigation
- Integrating OpenAPI/AsyncAPI specs into docs
- Deploying to GitHub, GitLab, Vercel, or Cloudflare
- Using MDX components (Cards, Steps, Tabs, Accordions, CodeGroup, Callouts)

## Don't Use When

- Building non-documentation websites (use standard web frameworks)
- Simple README files that don't need a hosted site
- Internal wikis better served by Notion or Confluence

## Quick Start

```bash
npm i -g mintlify
mint new          # Initialize new docs
mint dev          # Local preview on port 3000
mint validate     # Validate configuration
```

## Core Concepts

**Configuration:** `docs.json` defines theme, navigation, branding, colors, integrations.

**Themes:** mint, maple, palm, willow, linden, almond, aspen

**Navigation:** Tabs, anchors, groups, dropdowns, products, versions, languages (28+ locales).

**Components:** 26+ built-in: Cards, Steps, Tabs, Accordions, CodeGroup, Callouts, Mermaid, View, Tiles, Tree, Badge, Banner, Tooltips, Panel

## CLI Reference

```bash
mint dev                    # Local server on port 3000
mint broken-links           # Check for broken links
mint a11y                   # Accessibility audit
mint validate               # Validate docs.json config
mint openapi-check          # Validate OpenAPI specs
mint rename <old> <new>     # Rename file + update refs
mint migrate-mdx            # Migrate mint.json to docs.json
```

## Basic docs.json

```json
{
  "theme": "mint",
  "name": "My Docs",
  "colors": { "primary": "#0D9373" },
  "navigation": [
    { "group": "Getting Started", "pages": ["introduction", "quickstart"] }
  ]
}
```

## MDX Page Example

```mdx
---
title: "Getting Started"
description: "Quick introduction"
---

<Note>Important information</Note>

<Steps>
  <Step title="Install">Install the package</Step>
  <Step title="Configure">Set up config</Step>
</Steps>
```

## Key Features

- **API Docs:** Auto-generate from OpenAPI/AsyncAPI, interactive playgrounds
- **AI:** llms.txt, skill.md, MCP support
- **Analytics:** GA4, PostHog, Amplitude, Clarity, Mixpanel, and more
- **SEO:** Custom metatags, redirects, sitemap
- **Deployment:** Auto-deploy from GitHub/GitLab, preview deployments, custom domains

## Resources

- Official docs: https://mintlify.com/docs
- GitHub: https://github.com/mintlify