Comprehensive reference for building Mintlify documentation sites. Use when creating pages, configuring docs.json, adding components, setting up navigation, or working with API references. Routes to detailed reference files for all components and configuration options.

Mintlify reference Reference for building documentation with Mintlify. This file covers essentials that apply to every task. For detailed reference on specific topics, read the files listed in the reference index below. Reference index Read these files only when your task requires them . They are in the reference/ directory next to this file. To find them, look in the same directory as this skill file (e.g., .claude/skills/mintlify/reference/ ). File When to read reference/components.md Adding or modifying components (callouts, cards, steps, tabs, accordions, code groups, fields, frames, icons, tooltips, badges, trees, mermaid, panels, prompts, colors, tiles, updates, views). reference/configuration.md Changing docs.json settings (theme, colors, logo, fonts, appearance, navbar, footer, banner, redirects, SEO, integrations, API config). Also covers snippets, hidden pages, .mintignore, custom CSS/JS, and the complete frontmatter fields table. reference/navigation.md Modifying site navigation structure (groups, tabs, anchors, dropdowns, products, versions, languages, OpenAPI in nav). reference/api docs.md Setting up API documentation (OpenAPI, AsyncAPI, MDX manual API pages, extensions, playground config). Before you start Read the project's docs.json file first. It defines the site's navigation, theme, colors, and configuration. Search for existing content before creating new pages. You may need to update an existing page, add a section, or link to existing content rather than duplicating. Read 2 3 similar pages to match the site's voice, structure, and formatting. File format Mintlify uses MDX files ( .mdx or .md ) with YAML frontmatter. File naming Match existing patterns in the directory If no existing files or mixed file naming patterns, use kebab case: getting started.mdx Add new pages to docs.json navigation or they won't appear in the sidebar Internal links Use root relative paths without file extensions: /getting started/quickstart Do not use relative paths ( ../ ) or absolute URLs for internal pages Images Store images in an images/ directory. Reference with root relative paths. All images require descriptive alt text. Page frontmatter Every page requires title in its frontmatter. Include description and keywords for SEO. Common frontmatter fields Field Type Required Description title string Yes Page title in navigation and browser tabs. description string No Brief description for SEO. Displays under the title. sidebarTitle string No Short title for sidebar navigation. icon string No Lucide, Font Awesome, or Tabler icon name. Also accepts a URL or file path. tag string No Label next to page title in sidebar (e.g., "NEW"). hidden boolean No Remove from sidebar. Page still accessible by URL. mode string No Page layout: default , wide , custom , frame , center . keywords array No Search terms for internal search and SEO. api string No API endpoint for interactive playground (e.g., "POST /users" ). openapi string No OpenAPI endpoint reference (e.g., "GET /endpoint" ). Quick component reference Below are the most commonly used components. For full props and all 24 components, read reference/components.md . Callouts Steps Tabs and code groups bash npm install package name bash yarn add package name javascript example.js const greeting = "Hello, world!"; python example.py greeting = "Hello, world!" Cards and columns Use <Columns to arrange cards (or other content) in a grid. cols accepts 1 4. Accordions 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. mint validate — Validate documentation builds. mint upgrade — Upgrade from mint.json to docs.json . Writing standards Second person voice ("you"). Active voice, direct language. Sentence case for headings ("Getting started", not "Getting Started"). Sentence case for code block titles. All code blocks must have language tags. All images must have descriptive alt text. No marketing language, filler phrases, or emoji. Keep code examples simple, practical, and tested. Common mistakes Missing language tag on a code block (use ). Using relative paths ( ../page ) instead of root relative ( /section/page ). Forgetting to add new pages to docs.json navigation. Images without alt text. Adding file extensions to internal links ( /page.mdx instead of /page ).