mintlify

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/).

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.

project/
├── docs.json           # Site configuration (required)
├── index.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification (optional)
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx

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.

![Dashboard showing analytics overview](/images/dashboard.png

Page frontmatter

Every page requires title in its frontmatter. Include description and keywords for SEO.

Common frontmatter fields

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

<CodeGroup>
 
```javascript example.js
const greeting = "Hello, world!";

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 ```python, not ```).
• 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).