​

Mintlify best practices

​

Before you write

​

Understand the project

• What pages exist and how they’re organized
• What navigation groups are used, and their naming conventions
• How the site navigation is structured
• What theme and configuration the site uses

​

Check for existing content

• Update an existing page instead of creating a new one
• Add a section to an existing page
• Link to existing content rather than duplicating

​

Read surrounding content

​

Understand Mintlify components

​

Quick reference

​

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 in content
• mint rename - Rename/move files and update references
• mint validate - Validate documentation builds

​

Required files

• docs.json - Site configuration, including navigation, theme, integrations, etc. See global settings for all options.
• *.mdx files - Documentation pages with YAML frontmatter

​

Example file structure

project/
├── docs.json           # Site configuration
├── introduction.mdx
├── overview/
│   └── getting-started/
│       └── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx

​

Page frontmatter

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
---

• 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, such as default, wide, or custom.
• keywords: Array of terms related to the page content for local search and SEO.
• Any custom YAML fields for use with personalization or conditional content.

​

File conventions

• Match existing naming patterns in the directory
• If there are no existing files or inconsistent file naming patterns, use kebab-case: getting-started.mdx, api-reference.mdx
• Use root-relative paths without file extensions for internal links: /overview/getting-started/quickstart
• Do not use relative paths, like ../, or absolute URLs for internal pages
• When you create a new page, add it to docs.json navigation or it won’t appear in the sidebar

​

Philosophy of documentation

​

Frictionless onboarding

​

Productive friction

• Use heuristic stress tests. Present counter-hypotheses or use Socratic AI agents to force users to justify their approach.
• Embed unresolved vulnerabilities directly into theory modules to challenge assumptions.
• Reward long-term systemic investment by dynamically unlocking advanced documentation based on the user’s historical interaction and peer review.

​

Zero-player tutorials

• Present fully operational models where the system executes highly optimized, synergistic code in real-time. Expect the user to observe, reverse-engineer, and mimic optimal execution.
• Combat cognitive overload with progressive disclosure. Hide global elements and reveal only the specific tools and libraries needed for the immediate task.

​

Organize content

​

Navigation

​

Choose your primary pattern

• Groups: Default. Single audience, straightforward hierarchy
• Tabs: Distinct sections with different audiences, such as 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

• Groups - Organize related pages. Can nest groups within groups, but keep hierarchy shallow
• Menus - Add dropdown navigation within tabs for quick jumps to specific pages
• expanded: false - Collapse nested groups by default. Use for reference sections users browse selectively
• openapi - Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit

​

Links and paths

• Internal links: Root-relative, no extension: /overview/getting-started/quickstart
• Images: Store in /images, reference as /images/example.png
• External links: Use full URLs, they open in new tabs automatically

​

Customize docs sites

• Brand colors, fonts, logo → docs.json. See global settings
• Component styling, layout tweaks → custom.css at project root
• Dark mode → Enabled by default. Only disable with "appearance": "light" in docs.json if brand requires it

​

Write content

​

Components

​

Common decision points

• 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 confirmation
• <Danger> - High-risk actions or critical errors

​

Reusable content

• Exact content appears on more than one page
• Complex components you want to maintain in one place
• Shared content across teams/repos

• Slight variations needed per page, which lead to complex props

​

Writing standards

​

Voice and structure

• Second-person voice, using “you”
• Active voice, direct language
• Sentence case for headings, using “Getting started” and not “Getting Started”
• Sentence case for code block titles, using “Expandable example” and not “Expandable Example”
• Lead with context: explain what something is before how to use it
• Prerequisites at the start of procedural content
• Keep headings concise and self-explanatory in as few words as possible. Avoid using colons. Keep contextual markers (like dates) in the body text.
• Avoid repeatedly calling back to specific examples or analogies later in a document if they lose context.

​

What to avoid

• Marketing language like “powerful”, “seamless”, “robust”, or “cutting-edge”
• Filler phrases like “it’s important to note” or “in order to”
• Excessive conjunctions like “moreover”, “furthermore”, or “additionally”
• Editorializing words like “obviously”, “simply”, “just”, or “easily”
• Generic introductions that don’t add value
• Concluding summaries that restate what was just said
• Imaginative or anthropomorphic language to describe AI capabilities (e.g., avoid “intuition”, “brain”, or “thinking”; use “understanding”, “model”, or “processing”)
• Idioms and metaphors that obscure technical precision (e.g., avoid “black box”, “heavy lifting”, or “plumbing”; use literal descriptions)
• Specific, single-model references when discussing general AI capabilities. Use future-proof lists (e.g., “Gemini, Claude, or ChatGPT” instead of just “GPT-4”)

​

Terminology

• Use world memory instead of “agent memory”
• Use item / items in narrative text instead of “entity / entities” (exceptions apply to internal API/database names like the entity_types table or search-entities tools)

​

Formatting

• Use parentheses sparingly and only for direct definitions, such as acronyms. Otherwise, revise parenthetical thoughts into fluid, formal sentences.
• All code blocks must have language tags
• All images and media must have descriptive alt text
• Use bold and italics only when they serve the reader’s understanding—never use text styling just for decoration
• No decorative formatting or emoji (exception: decorative emojis are permitted in footer sections)
• Do not use horizontal rules (---) for section separation or decorative purposes, unless specifically required for cosmetic formatting in high-fidelity narratives. Heading hierarchy alone should define the structure.

​

Code examples

• Keep examples simple and practical
• Use realistic values rather than generic names like “foo” or “bar”
• One clear example is better than multiple variations
• Test that code works before including it

​

Document APIs

• OpenAPI spec: Add to docs.json with "openapi": ["openapi.yaml"]. Pages auto-generate. Reference in navigation as GET /endpoint. This is the most efficient and sustainable approach.
• Manual pages: Write endpoints manually with api: "POST /users" in frontmatter. More work but full control.
• Hybrid: Use OpenAPI for most endpoints, manual pages for complex workflows.

​

Deploy

​

What agents can configure

• Redirects → Add to docs.json with "redirects": [{"source": "/old", "destination": "/new"}]
• SEO indexing → Control with "seo": {"indexing": "all"} to include hidden pages in search

​

Requires dashboard setup, which is a human task

• Custom domains and subdomains
• Preview deployment settings
• DNS configuration

​

Workflow

• Understand task and project: Review your core platform configuration docs.json. Know the navigation setup, theme, and routing constraints.
• Check for existing content: Always search first. Update an existing page instead of adding a new one.
• Read surrounding content: Read two to three existing pages to internalize the established voice, tone, and level of detail.
• Plan: Outline the necessary updates. Lead with what the reader accomplishes.
• Write: Put the most important information first. Keep paragraphs scannable. Format with active voice. Use TODO comments for uncertain details.
• Update navigation: Bind new content paths to the site’s structural configuration file.
• Verify: Check frontmatter, language tags, broken internal links, and tone rules. Run mint broken-links and mint validate.

​

Communications and social strategy

• Signal over noise: Skip marketing jargon. Identify the immediate value this update gives the user.
• Reciprocity: Offer specific value via blueprints, code snippets, architectures before asking for engagement.
• Mimetic desire: Highlight adoption by high-impact engineers or ecosystem partners.
• The pratfall effect: Be radically transparent. Acknowledge past flaws to build trust.
• Open-source transparency: Be fully transparent about friction (Docker, databases, authentication) when documenting self-hosted paths. Users require accurate information to choose between local or managed cloud options.
• Mere exposure effect: Be consistent in your visual styling and voice.
• Curse of knowledge: Remember that what is obvious to the engineer is never obvious to the new user.

​

Sources and citations

• Mintlify documentation best practices
• Ludic pedagogy: The mechanics of antagonism and zero-player tutorials in technical documentation design
• TrustGraph documentation strategy
• Supermemory resource guide
• Google developer documentation style guide: Active voice