mintlify-docs

name	mintlify-docs
description	Writes and maintains Mintlify-compatible documentation content. Use when creating or editing MDX pages, configuring docs.json, using supported Mintlify components, setting up navigation, or working with OpenAPI specs. This skill covers content structure, not running the camelAI docs preview.

Mintlify Documentation

Working Relationship

• Push back on ideas when it leads to better documentation. Cite sources and explain reasoning.

Project Context

• Format: MDX files with YAML frontmatter
• Config: docs.json for navigation, theme, settings
• Renderer: open-mdx-docs; use the running-camelai-docs skill for local preview
• Never run mint dev or mintlify dev in this repository; those launch the retired site experience
• Schema reference: https://mintlify.com/docs.json

Content Strategy

• Document just enough for user success — not too much, not too little
• Prioritize accuracy and usability
• Make content evergreen when possible
• Search for existing content before adding anything new. Avoid duplication unless strategic
• Check existing patterns for consistency
• Start by making the smallest reasonable changes

Frontmatter

Every MDX page requires frontmatter. Common fields:

Field	Required	Description
title	Yes	Clear, descriptive page title
description	Yes	Concise summary for SEO/navigation
sidebarTitle	No	Abbreviated sidebar label
icon	No	Sidebar icon name
mode	No	Layout: default, wide, custom, frame, center
api	No	API endpoint for playground (e.g., POST /users)
openapi	No	OpenAPI spec reference
hidden	No	Hide from sidebar (URL still works)
slug	No	Custom URL path

Full frontmatter reference: reference/frontmatter.md

Writing Standards

• Second-person voice ("you")
• Prerequisites at start of procedural content
• Test all code examples before publishing
• Match style and formatting of existing pages
• Include both basic and advanced use cases
• Language tags on all code blocks
• Alt text on all images
• Relative paths for internal links

Linking to Sections (Anchors)

Mintlify auto-generates an anchor slug from each heading's text. It lowercases, replaces spaces with hyphens, and keeps punctuation — apostrophes and commas survive in the slug (URL-encoded as %E2%80%99 and %2C), they aren't stripped.

Do not use {#custom-id} heading-anchor syntax. Real Mintlify renders MDX, where {...} is a JavaScript expression — so ## Heading {#my-id} fails to compile with Could not parse expression with acorn and the whole page shows a parsing error. (A Mintlify-clone may have accepted this; the live Mintlify build does not.)

To get a clean, stable deep-link target, write the heading itself with no punctuation so its auto-slug is predictable:

## Using an unsupported provider through OpenRouter

Then link with the matching slug:

[See unsupported providers](#using-an-unsupported-provider-through-openrouter)
[See unsupported providers](/plans/model-providers#using-an-unsupported-provider-through-openrouter)

When in doubt about a slug, run mint dev and grep the rendered HTML for the heading's id="..." rather than guessing.

Do Not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples

Components

Use Mintlify's built-in components. Quick reference for the most common ones:

Component	Use For
<Card>	Linked content blocks with icon/image
<Columns cols={N}>	Grid layout (1-4 columns)
<Tabs> / <Tab>	Tabbed content sections
<Accordion>	Collapsible content
<CodeGroup>	Multiple code blocks with tabs
<Steps> / <Step>	Sequential instructions
<Note>, <Warning>, <Info>, <Tip>, <Check>, <Danger>	Callout boxes
<Tooltip>	Hover text
<Frame>	Image wrapper with caption
<Expandable>	Expandable parameter details

Full component reference with props: reference/components.md

docs.json Structure

The docs.json file controls site-wide configuration. Key sections:

• theme — Layout theme (mint, maple, palm, willow, linden, almond, aspen, sequoia, luma)
• name — Project name
• colors — primary, light, dark hex values
• logo — Light/dark mode logo paths
• navigation — Tabs, groups, pages, anchors, dropdowns
• navbar — Top nav links and primary CTA button
• footer — Social links and footer columns
• api — OpenAPI specs, playground settings, auth config

Full docs.json reference: reference/docs-json.md

Navigation

Navigation is a recursive structure in docs.json. Building blocks:

• Pages — Array of file path strings (e.g., "getting-started/overview")
• Groups — Collapsible sidebar sections with group, pages, optional icon/tag/expanded/root
• Tabs — Top-level horizontal sections with tab and nested groups
• Anchors — Persistent sidebar items with anchor, href, icon
• Dropdowns — Expandable top-sidebar menus
• Versions — Version-specific partitions
• Products — Separate product documentation areas

These can be arbitrarily mixed and nested. Full details: reference/navigation.md

Code Blocks

```python title="example.py" highlight={2} lines
import os
key = os.getenv("API_KEY")  # this line is highlighted
```

Features: lines (line numbers), highlight={1-2,5}, focus={2,4-5}, title="Label", wrap, expandable.

Visual diffs in code: // [!code ++] and // [!code --] comments.

Use <CodeGroup> to show multiple languages:

<CodeGroup>
```python Python
print("hello")
```
```javascript JavaScript
console.log("hello")
```
</CodeGroup>

Reusable Snippets

Place reusable MDX in /snippets/ (not rendered as pages). Import and use:

import MySnippet from "/snippets/my-snippet.mdx";

<MySnippet />

Snippets support props for parameterized content.

API Documentation

Three approaches for OpenAPI-based API docs:

1. Auto-generate from spec — Set "openapi": "spec.json" at group level in navigation
2. Selective endpoints — Use "METHOD /path" strings in pages array
3. Custom MDX pages — Use openapi frontmatter field

Full API docs reference: reference/api-docs.md

Images and Assets

• Store anywhere in repo; path maps to URL
• Reference: ![alt text](/images/my-image.png) or wrap with <Frame caption="...">
• Max file size: 20 MB for images, 100 MB for other files
• Supported: PNG, JPG, GIF, WebP, SVG, ICO, MP4, WebM, MP3, WAV, JSON, YAML, CSS, JS, WOFF/WOFF2/TTF

Variables

Define in docs.json under variables, use as {{variableName}} anywhere in content.

Deployment

Push to GitHub with the Mintlify GitHub App installed. Deploys are automatic — no build steps needed.