From doc-reviewer
Builds and maintains Mintlify documentation sites by creating MDX pages, configuring docs.json navigation and themes, adding components, and setting up API references.
npx claudepluginhub yangleyland/docs --plugin doc-authorThis skill uses the workspace's default tool permissions.
**Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.**
Writes, edits, and maintains documentation collaboratively or autonomously via git PRs. Defaults to human-led mode; verifies context before drafting Markdown/MDX content.
Structures documentation sites with navigation, sections like Getting Started, Guides, API Reference, Troubleshooting, plus content organization and best practices.
Generates customized Docusaurus documentation websites from project content. Analyzes structure, iteratively builds and validates, creates git branch and commits.
Share bugs, ideas, or general feedback.
Always consult mintlify.com/docs for components, configuration, and latest features.
If you are not already connected to the Mintlify MCP server, https://mintlify.com/docs/mcp, add it so that you can search more efficiently.
Always favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.
Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the docs.json file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.
Full schema at mintlify.com/docs.json.
Read docs.json in the project root. This file defines the entire site: navigation structure, theme, colors, links, API and specs.
Understanding the project tells you:
Search the docs before creating new pages. You may need to:
Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail.
Review the Mintlify components to select and use any relevant components for the documentation request that you are working on.
npm i -g mint - Install the Mintlify CLImint dev - Local preview at localhost:3000mint broken-links - Check internal linksmint a11y - Check for accessibility issues in contentmint validate - Validate documentation buildsdocs.json - Site configuration (navigation, theme, integrations, etc.). See global settings for all options.*.mdx files - Documentation pages with YAML frontmatterproject/
├── docs.json # Site configuration
├── introduction.mdx
├── quickstart.mdx
├── guides/
│ └── example.mdx
├── openapi.yml # API specification
├── images/ # Static assets
│ └── example.png
└── snippets/ # Reusable components
└── component.jsx
Every page requires title in its frontmatter. Include description for SEO and navigation.
---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
---
Optional frontmatter fields:
sidebarTitle: Short title for sidebar navigation.icon: Lucide or Font Awesome icon name, URL, or file path.tag: Label next to the page title in the sidebar (for example, "NEW").mode: Page layout mode (default, wide, custom).keywords: Array of terms related to the page content for local search and SEO.getting-started.mdx, api-reference.mdx/getting-started/quickstart../) or absolute URLs for internal pagesdocs.json navigation or it won't appear in the sidebarWhen a user asks about anything related to site-wide configurations, start by understanding the global settings. See if a setting in the docs.json file can be updated to achieve what the user wants.
The navigation property in docs.json controls site structure. Choose one primary pattern at the root level, then nest others within it.
Choose your primary pattern:
| Pattern | When to use |
|---|---|
| Groups | Default. Single audience, straightforward hierarchy |
| Tabs | Distinct sections with different audiences (Guides vs API Reference) or content types |
| Anchors | Want persistent section links at sidebar top. Good for separating docs from external resources |
| Dropdowns | Multiple doc sections users switch between, but not distinct enough for tabs |
| Products | Multi-product company with separate documentation per product |
| Versions | Maintaining docs for multiple API/product versions simultaneously |
| Languages | Localized content |
Within your primary pattern:
expanded: false - Collapse nested groups by default. Use for reference sections users browse selectivelyopenapi - Auto-generate pages from OpenAPI spec. Add at group/tab level to inheritCommon combinations:
/getting-started/quickstart/images, reference as /images/example.pngWhat to customize where:
docs.json. See global settingscustom.css at project root"appearance": "light" in docs.json if brand requires itStart with docs.json. Only add custom.css when you need styling that config doesn't support.
The components overview organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component.
Common decision points:
| Need | Use |
|---|---|
| Hide optional details | <Accordion> |
| Long code examples | <Expandable> |
| User chooses one option | <Tabs> |
| Linked navigation cards | <Card> in <Columns> |
| Sequential instructions | <Steps> |
| Code in multiple languages | <CodeGroup> |
| API parameters | <ParamField> |
| API response fields | <ResponseField> |
Callouts by severity:
<Note> - Supplementary info, safe to skip<Info> - Helpful context such as permissions<Tip> - Recommendations or best practices<Warning> - Potentially destructive actions<Check> - Success confirmationWhen to use snippets:
When NOT to use snippets:
Import snippets with import { Component } from "/path/to/snippet-name.jsx".
Never use:
Watch for AI-typical patterns:
Choose your approach:
docs.json with "openapi": ["openapi.yaml"]. Pages auto-generate. Reference in navigation as GET /endpointapi: "POST /users" in frontmatter. More work but full controlEncourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option.
Mintlify deploys automatically when changes are pushed to the connected Git repository.
What agents can configure:
docs.json with "redirects": [{"source": "/old", "destination": "/new"}]"seo": {"indexing": "all"} to include hidden pages in searchRequires dashboard setup (human task):
For /docs subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See /docs subpath.
Identify what needs to be documented, which pages are affected, and what the reader should accomplish afterward. If any of these are unclear, ask.
docs.json to understand the site structure{/* TODO: Verify the default timeout value */}
If you created a new page, add it to the appropriate group in docs.json.
Before submitting:
docs.json navigationmint broken-links to check linksmint validate to find any errorsIf a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the @mintlify/scraping CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components.
Any page that is not included in the docs.json navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation.
The .mintignore file is used to exclude files from a documentation repository from being processed.
title at minimummint.json - mint.json is deprecated. Only ever use docs.json