mintlify

The mintlify skill is a comprehensive reference for building Mintlify documentation sites. It is used when creating pages, configuring docs.json, adding components, setting up navigation, or working with API references. The main file covers essentials that apply to every task and routes to detailed reference files for the full set of components and configuration options, so that documentation work stays consistent with Mintlify conventions.

It provides a reference index pointing to reference/components.md (callouts, cards, steps, tabs, accordions, code groups, and more), reference/configuration.md (docs.json settings such as theme, colors, logo, fonts, navbar, footer, redirects, SEO, snippets, frontmatter fields), reference/navigation.md (groups, tabs, anchors, dropdowns, products, versions, languages), and reference/api-docs.md (OpenAPI, AsyncAPI, MDX API pages, playground config). The skill uses MDX files (.mdx or .md) with YAML frontmatter, documents a standard project structure with docs.json as the required configuration file, and specifies file naming (kebab-case), internal links (root-relative paths without extensions), and image handling (in an images/ directory with descriptive alt text). It details required and common frontmatter fields like title, description, sidebarTitle, icon, tag, hidden, mode, keywords, api, and openapi, and gives quick examples of callouts (Note, Info, Tip, Warning, Check, Danger), Steps, Tabs, CodeGroup, Cards, Columns, and Accordions. CLI commands include npm i -g mint, mint dev, mint broken-links, mint a11y, mint validate, and mint upgrade.

It targets technical writers and developers maintaining Mintlify docs, and it enforces writing standards such as second-person voice, active voice, sentence case headings, language tags on all code blocks, and alt text on all images, while avoiding marketing language and emoji. The skill advises reading docs.json first, searching for existing content before creating pages, and reviewing 2-3 similar pages to match voice and structure. It notes common mistakes like missing code-block language tags, relative instead of root-relative links, forgetting to add new pages to docs.json navigation, and images without alt text. It works with any Mintlify documentation project and requires a docs.json configuration file.