Mintlify reference

Reference for working on Mintlify projects. 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.

File	When to read
reference/components.md	Adding or modifying components (callouts, cards, steps, tabs, accordions, code groups, fields, frames, icons, tooltips, badges, trees, mermaid, MDX, panels, prompts, colors, tiles, updates, views). Also covers table column widths.
reference/configuration.md	Changing docs.json settings (theme, colors, logo, fonts, appearance, navbar, footer, banner, redirects, SEO, integrations, API config). Also covers snippets, hidden pages, .mintignore, custom CSS/JS, and the complete frontmatter fields table.
reference/navigation.md	Modifying site navigation structure (groups, tabs, anchors, dropdowns, products, versions, languages, OpenAPI, and SDK references in nav).
reference/api-docs.md	Setting up API documentation (OpenAPI, AsyncAPI, MDX manual API pages, extensions, playground config).
reference/cli.md	Running common CLI commands (dev, validate, add-domain, analytics, score, broken-links, a11y, format, and config) and their key flags.
reference/product-context.md	Before substantial content work (new site, broad restructure, first-time section setup) — check for and maintain .mintlify/product-brief.md.

MCP servers

Two Mintlify MCP servers are available. Use them alongside the reference files in this skill.

Mintlify Search

Read-only access to Mintlify's published documentation. Use it when the reference files don't cover a specific detail, when you need an up-to-date component signature, or to verify an unfamiliar config option.

Tools:

• search_mintlify — Search the Mintlify knowledge base by query. Good for finding guides, examples, and API references.
• query_docs_filesystem_mintlify — Browse the docs file tree (ls, cat, grep, find, etc.). Good for reading a specific docs page.
• submit_feedback — Report a docs page that is incorrect, outdated, confusing, or incomplete.

Mintlify Admin

Write access to a Mintlify project. Requires OAuth on first use. Complete authentication in the browser when prompted.

Use this server when the user wants to edit their Mintlify content, restructure navigation, or open a pull request. Content changes buffer on a session branch; nothing touches the deploy branch until save. Project management changes made through code mode apply immediately to the live project without a branch or pull request.

Workflow: call checkout first (always), then use read/search/edit_page/write_page/list_nodes/create_node/update_node/move_node/delete_node/update_config to make changes, then call save to publish (or discard_session to abandon).

Key tools:

• checkout — Start a session on a branch (required first call). Returns a branch-level editorUrl to preview changes live.
• list_branches — List existing branches; call before checkout to attach to one.
• list_deployments — Discover which project(s) this connection can access.
• read / search — Fetch a page's MDX or search across pages.
• edit_page / write_page — Apply targeted edits or overwrite a page.
• list_nodes / create_node / update_node / move_node / delete_node — Manage the navigation tree. If a create_node, update_node, move_node, or delete_node call leaves the navigation invalid (for example, a page at the root next to tabs), the response includes a navigationErrors field. Fix these errors before save, because Mintlify can drop invalid nodes from the published navigation.
• update_config — Modify docs.json (theme, nav roots, integrations, SEO).
• upload_image / finalize_image_upload — Add a local image to the session branch. Call upload_image with the destination path (for example, images/dashboard.png), contentType, and exact size in bytes. PUT the file bytes to the returned uploadUrl with the returned headers, then call finalize_image_upload with the uploadId and the same path. Use the returned src in MDX or in the docs.json logo or favicon fields. Uploading to an existing path replaces the image. Mintlify only accepts SVGs for logos and favicons, so pass purpose: "logo" to both tools. Images publish with the session on save.
• search_code_operations / execute_code — Code mode for project-level operations with no dedicated tool (workflows, settings, members, billing, integrations, analytics, private-page sharing). Search available methods, then run a TypeScript script against them. No checkout required. Writes apply immediately to the live project, so confirm the intended change first.

Private pages: list_nodes accepts visibility: "private" to list the private pages and folders the OAuth user can access (ignores other filters, returns each node's role). read, edit_page, write_page, update_node, and delete_node accept private-page-<uuid> or private-folder-<uuid> node ids; create_node accepts visibility: "private" with data.type: "page" or "group". Private-page operations require an OAuth session (the admin MCP rejects client and machine-to-machine tokens), work without a checkout, and enforce role requirements: read for reads, editor or higher for writes and updates, manager for deletes. The caller becomes the manager of any node they create.

• diff — See all changes relative to the deploy branch.
• get_session_state — Check the current session's status.
• save — Publish the session. mode: "auto" (default) opens a PR, and Mintlify merges it immediately when the project's publishing setting allows direct pushes and the deploy branch isn't protected. mode: "pr" always opens a PR and leaves it open for review. mode: "commit" pushes to an existing PR branch without opening a new PR. Changing the publishing setting in the dashboard requires the admin role. Unless the save merges immediately, the response includes an editorUrl that opens the first created or updated page.
• discard_session — Drop all in-session changes.

Keep each session focused on one change. Smaller sessions produce easier-to-review PRs. Open the editorUrl to watch changes render live. Prefer the page-level editorUrl from create_node or save over the one from checkout.

Before you start

Before substantial content work, read reference/product-context.md and check for .mintlify/product-brief.md.

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

Include title, description, and keywords in frontmatter. title is technically optional (Mintlify generates one from the file path if omitted), but set it explicitly for clarity and SEO.

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---

Common frontmatter fields

Field	Type	Description
title	string	Page title in navigation and browser tabs. Auto-generated from the path if omitted.
description	string	Brief description for SEO. Displays under the title.
sidebarTitle	string	Short title for sidebar navigation.
icon	string	Lucide, Font Awesome, or Tabler icon name. Also accepts a single emoji, a URL, or a file path.
tag	string	Label next to page title in sidebar (e.g., "NEW").
hidden	boolean	Remove from sidebar. Page still accessible by URL.
mode	string	Page layout: default, wide, custom, frame, center.
keywords	array	Search terms for internal search and SEO.
api	string	API endpoint for interactive playground (e.g., "POST /users").
openapi	string	OpenAPI endpoint reference (e.g., "GET /endpoint").

For the complete list including searchable, boost, deprecated, related, groups, and more, read reference/configuration.md.

Quick component reference

Below are the most commonly used components. For full props and all 26 components, read reference/components.md.

Callouts

<Note>Supplementary information, safe to skip.</Note>
<Info>Helpful context such as permissions or prerequisites.</Info>
<Tip>Recommendations or best practices.</Tip>
<Warning>Potentially destructive actions or important caveats.</Warning>
<Check>Success confirmation or completed status.</Check>
<Danger>Critical warnings about data loss or breaking changes.</Danger>

Steps

<Steps>
  <Step title="First step">
    Instructions for step one.
  </Step>
  <Step title="Second step">
    Instructions for step two.
  </Step>
</Steps>

Tabs and code groups

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

<CodeGroup>

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

```python example.py
greeting = "Hello, world!"
```

</CodeGroup>

Cards and columns

<Columns cols={2}>
  <Card title="First card" icon="rocket" href="/quickstart">
    Card description text.
  </Card>
  <Card title="Second card" icon="book" href="/guides">
    Card description text.
  </Card>
</Columns>

Use <Columns> to arrange cards (or other content) in a grid. cols accepts 1-4.

Accordions

<AccordionGroup>
  <Accordion title="First section">Content one.</Accordion>
  <Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>

CLI commands

Install with npm i -g mint. Key commands: mint dev (local preview), mint validate, mint broken-links, mint a11y, mint test (generate tests for code blocks), mint score, mint analytics (traffic, search, feedback, and assistant conversations; Pro and Enterprise plans), mint new, mint signup, mint index (install the Mintlify Index MCP server in supported coding agents). Read reference/cli.md for full flags and subcommands.

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

• Using mint.json — it is deprecated. The config file is always docs.json.
• 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).