| name | mintlify-docs |
| description | Structure, write, build, and maintain documentation sites with Mintlify (docs.json + MDX pages). Use when creating or scaffolding a docs site, adding or editing docs pages, reorganizing docs navigation, reviewing docs quality, or validating and deploying Mintlify documentation. |
Mintlify Docs
Mintlify is a docs-as-code platform: a repo with one docs.json (site config +
navigation) and MDX pages, deployed automatically on git push once the repo is
connected in the Mintlify dashboard.
Anatomy of a docs repo:
docs.json # site config: name, theme, colors, navigation — the source of truth
index.mdx # landing page; every page is an .mdx file with YAML frontmatter
guides/*.mdx
reference/*.mdx
snippets/*.mdx # reusable content, imported by pages, never rendered standalone
images/, logo/ # static assets
Every page needs frontmatter with at least title and description. A page
only appears in the sidebar if it is listed in docs.json navigation (path
without the .mdx extension).
Workflows
Scaffold a new docs site
Copy assets/starter/ into the target directory and adapt
name, colors, and navigation in docs.json. Alternatively mint new
generates Mintlify's official starter. Then fill pages per the structure below.
Structure content
Decide each page's type before writing — it dictates structure and tone:
- Tutorial — hands-on first success for beginners; one complete path, minimal choices.
- How-to guide — a specific task for someone who knows the basics; steps, no theory.
- Reference — complete, accurate, scannable lookup (tables, parameters, defaults).
- Explanation — the "why": architecture, trade-offs, design decisions.
Don't mix types on one page; link between them instead. Most internal docs need
how-to guides and reference first. Group pages in docs.json by user goal, not
by internal team structure. Use tabs for genuinely separate audiences/products,
groups within a tab for topics. Full navigation schema: references/docs-json.md.
Write pages
- Frontmatter on every page; second-person voice; prerequisites stated up front
for procedural content; relative paths for internal links (
/guides/setup,
never absolute URLs to the site itself).
- Use MDX components where they genuinely aid scanning —
<Steps> for
procedures, <Note>/<Warning> callouts, <CodeGroup> for multi-language
examples, ```mermaid for diagrams. Cheatsheet: references/components.md.
- Only include commands/code you have actually run or verified against the
codebase. Never invent flags, options, or behavior — check the source.
- Search existing pages before adding new ones; extend rather than duplicate.
Repeated fragments go in
snippets/ and get imported.
- Frontmatter/page options and writing standards: references/writing.md.
Validate
CLI (npm i -g mint, Node >= 20.17; mint update to upgrade):
mint dev
mint validate
mint broken-links
mint a11y
mint format
mint deslop
Deploy
Push to the production branch → auto-deploy to https://<project>.mintlify.site
(requires the Mintlify GitHub app connected to the repo, one-time dashboard
setup). PRs get preview deployment URLs. Never merge without mint validate
passing.
Maintain
When code changes, update the affected pages in the same PR. Periodically:
mint broken-links, prune pages for features that no longer exist, and check
that navigation still matches how users approach the product. Prefer the
smallest change that fixes the problem; big restructures need redirects
(redirects in docs.json) so old URLs keep working.
Looking things up
- Mintlify reference is available live through the
mintlify-docs MCP
connector (via the mcp tool): search the official docs for any docs.json
property, component, or CLI detail instead of guessing.
- Any Mintlify docs page is fetchable as markdown by appending
.md to its
URL; the full page map is at https://mintlify.com/docs/llms.txt.
