praxis

Capabilities

Mintlify enables agents to build and manage comprehensive documentation sites with API reference documentation, customizable styling, and AI-assisted content creation. Agents can create multi-page documentation with hierarchical navigation, embed code examples, generate API docs from OpenAPI specifications, and deploy documentation automatically through GitHub integration.

Skills

Documentation Creation and Content Management

• Write documentation pages using MDX syntax with support for markdown formatting, code blocks, images, and HTML embeds
• Create hierarchical navigation with tabs, groups, and nested pages using the docs.json configuration file
• Add code examples with syntax highlighting for multiple programming languages using fenced code blocks
• Embed media including images, videos, and iframes with customizable sizing and styling
• Create reusable snippets that can be imported across multiple pages to maintain consistency and reduce duplication

API Documentation

• Auto-generate API documentation from OpenAPI specifications (JSON format)
• Configure API endpoints with GET, POST, DELETE, and webhook support
• Set up authentication using Bearer tokens, basic auth, or API keys with configurable playground modes
• Create interactive API playgrounds where users can test endpoints with authentication
• Document request/response schemas with parameter descriptions, examples, and error codes

Site Customization and Configuration

• Customize global settings via docs.json including project name, logo, favicon, and color scheme
• Configure color themes with primary colors, dark mode support, and background customization
• Set up navigation structure with tabs, groups, and nested pages for organizing content
• Add topbar links and CTA buttons for navigation and GitHub repository integration
• Configure footer social media links for website, X, Discord, Slack, GitHub, LinkedIn, and other platforms
• Enable feedback mechanisms with “suggest edit” and “raise issue” buttons for community contributions
• Customize dark mode toggle with default mode selection and visibility options

Development and Local Preview

• Install Mintlify CLI using npm i -g mint for local development
• Preview documentation locally with mint dev command at http://localhost:3000
• Customize preview port using --port flag (e.g., mint dev --port 3333)
• Validate broken links using mint broken-links command
• Update CLI versions with npm mint update to stay synchronized with production

AI-Assisted Writing Tools

• Integrate with Cursor editor by installing Mintlify skill with npx skills add https://mintlify.com/docs
• Use Claude Code for AI-assisted documentation writing with active Claude subscription
• Configure Windsurf’s Cascade AI assistant for documentation drafting and editing
• Customize project instructions via AGENTS.md file for project-specific terminology and style preferences
• Access component reference and writing standards through installed AI skills

Deployment and Publishing

• Deploy automatically through GitHub app integration from the dashboard
• Publish documentation by committing and pushing changes to GitHub
• Manage multiple documentation versions with version dropdown in navigation bar
• Configure multiple base URLs for API endpoints with user-selectable options

Workflows

Setting Up a New Documentation Site

1. Clone documentation repository locally
2. Install Mintlify CLI: npm i -g mint
3. Navigate to docs directory and run: mint dev
4. Open http://localhost:3000 to preview
5. Edit docs.json to update project name and colors
6. Commit and push changes to deploy automatically

Creating API Documentation from OpenAPI

1. Prepare OpenAPI specification file (JSON format)
2. Configure docs.json with API settings:
   • Set baseUrl for API endpoints
   • Configure authentication method (bearer, basic, or key)
   • Point openapi field to specification file URL or relative path
3. Create endpoint pages with frontmatter: openapi: 'GET /endpoint'
4. Configure playground mode (show, simple, or hide)
5. Deploy through GitHub integration

Building Documentation with AI Assistance

1. Open docs directory in Cursor, Claude Code, or Windsurf
2. Install Mintlify skill: npx skills add https://mintlify.com/docs
3. Edit AGENTS.md with project-specific guidelines
4. Use AI editor features to draft and edit documentation
5. Preview changes locally with mint dev
6. Commit and push to deploy

Organizing Complex Documentation

1. Create folder structure for content organization
2. Define navigation in docs.json with tabs and groups
3. Use nested navigation for sub-sections
4. Create reusable snippets in /snippets directory
5. Import snippets into pages using MDX imports
6. Link between pages using root-relative paths

Integration

Mintlify integrates with multiple development tools and platforms:

• GitHub: Automatic deployment through GitHub app integration; supports GitHub stars display in topbar
• OpenAPI: Auto-generates API documentation from OpenAPI 3.0 specifications
• Cursor Editor: AI-assisted documentation writing with Mintlify skill
• Claude Code: Integration with Anthropic’s Claude for documentation assistance
• Windsurf: Cascade AI assistant for documentation workflows
• Node.js: CLI-based development with npm package management
• Markdown/MDX: Full support for markdown syntax with JSX component extensions

Context

Documentation Structure

Mintlify uses a file-based architecture where MDX files in the root and subdirectories become pages. The docs.json file serves as the central configuration file controlling navigation, styling, and API settings. Pages must be explicitly added to docs.json to appear in navigation, though they remain accessible via direct links and search.

Navigation Patterns

Navigation is organized hierarchically with tabs containing groups containing pages. Nested navigation allows sub-groups within pages. Folder names in the file system should match navigation paths (e.g., your-folder/your-page.mdx for /your-folder/your-page URLs). The reserved folder name api cannot be used at the top level due to Next.js constraints.

API Documentation

OpenAPI specifications define all API endpoints, authentication methods, and request/response schemas. The API playground allows interactive testing with authentication. Multiple OpenAPI files can be configured for different API versions or services.

Content Reusability

Snippets in the /snippets directory can be imported as components, variables, or default exports. This enables maintaining consistent content across multiple pages without duplication. Snippets support parameterization through props.

Deployment Model

Mintlify uses a GitHub-based deployment model where changes are automatically deployed when pushed to the repository. The GitHub app must be installed from the dashboard to enable automatic deployments. Local preview with mint dev allows testing before deployment.

Customization Scope

All visual customization happens through docs.json configuration. Color schemes support both light and dark modes with separate hex values. The platform uses Font Awesome icons for navigation elements and supports custom fonts through CSS. Background images can be applied globally to all pages.

For additional documentation and navigation, see: https://praxis-a3dca7d3.mintlify.app/llms.txt