Mintlify Documentation Generator for Claude

The `/mintlify-docs` command generates comprehensive, production-ready documentation using Mintlify with AI-powered content creation, API reference automation, and interactive MDX components.

## Usage

```
/mintlify-docs [options] <documentation_scope>
```

## Options

### Documentation Types
- `--quickstart` - Generate quickstart guide
- `--api-reference` - Generate API reference from code
- `--tutorial` - Generate step-by-step tutorial
- `--guide` - Generate conceptual guide
- `--changelog` - Generate changelog from git history

### Source Analysis
- `--from-code=<path>` - Generate docs from source code
- `--from-openapi=<path>` - Generate API docs from OpenAPI spec
- `--from-types=<path>` - Generate docs from TypeScript types
- `--from-jsdoc` - Extract JSDoc comments

### Output Format
- `--mdx` - Generate MDX with components (default)
- `--markdown` - Generate plain Markdown
- `--with-examples` - Include code examples
- `--with-snippets` - Include interactive snippets

### Features
- `--search` - Configure search integration
- `--navigation` - Generate navigation structure
- `--analytics` - Add analytics tracking
- `--versioning` - Enable version management

## Examples

### API Reference from TypeScript

**Command:**
```
/mintlify-docs --api-reference --from-types=src/api/users.ts --with-examples
```

**Input Code:**
```typescript
// src/api/users.ts
/**
 * User management API client
 * @module UserAPI
 */

export interface User {
  /** Unique user identifier */
  id: string;
  /** User's email address */
  email: string;
  /** Display name */
  name: string;
  /** User role */
  role: 'admin' | 'user' | 'guest';
  /** Account creation timestamp */
  createdAt: Date;
}

export interface CreateUserInput {
  email: string;
  name: string;
  password: string;
}

/**
 * Retrieves a user by ID
 * @param userId - The user's unique identifier
 * @returns Promise resolving to the user object
 * @throws {NotFoundError} If user doesn't exist
 * @throws {AuthorizationError} If caller lacks permission
 * @example
 * ```typescript
 * const user = await getUser('user_123');
 * console.log(user.name);
 * ```
 */
export async function getUser(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) throw new Error('Failed to fetch user');
  return response.json();
}

/**
 * Creates a new user
 * @param input - User creation data
 * @returns Promise resolving to the created user
 * @throws {ValidationError} If input is invalid
 * @throws {ConflictError} If email already exists
 * @example
 * ```typescript
 * const newUser = await createUser({
 *   email: 'user@example.com',
 *   name: 'John Doe',
 *   password: 'secure-password'
 * });
 * ```
 */
export async function createUser(input: CreateUserInput): Promise<User> {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  });
  if (!response.ok) throw new Error('Failed to create user');
  return response.json();
}
```

**Generated Documentation:**
```mdx
---
title: 'User API'
description: 'Manage user accounts and profiles'
icon: 'users'
---

# User Management API

The User API provides endpoints for managing user accounts, authentication, and profiles.

## User Object

The User object represents a user account in your application.

<ResponseField name="id" type="string" required>
  Unique user identifier
</ResponseField>

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name
</ResponseField>

<ResponseField name="role" type="'admin' | 'user' | 'guest'" required>
  User role determining access permissions
</ResponseField>

<ResponseField name="createdAt" type="Date" required>
  Account creation timestamp
</ResponseField>

<CodeGroup>

```typescript User Object
interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user' | 'guest';
  createdAt: Date;
}
```

```json Example
{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2025-10-16T12:00:00Z"
}
```

</CodeGroup>

## Get User

<div className="api-method">
  <div className="api-method-label">GET</div>
  <div className="api-method-path">/api/users/:userId</div>
</div>

Retrieves a user by their unique identifier.

### Path Parameters

<ParamField path="userId" type="string" required>
  The user's unique identifier
</ParamField>

### Response

<ResponseField name="user" type="User">
  The requested user object
</ResponseField>

### Error Codes

<ResponseField name="404" type="NotFoundError">
  User with the specified ID doesn't exist
</ResponseField>

<ResponseField name="403" type="AuthorizationError">
  Caller lacks permission to access this user
</ResponseField>

<CodeGroup>

```typescript TypeScript SDK
import { getUser } from '@/api/users';

const user = await getUser('user_123');
console.log(user.name); // "John Doe"
```

```javascript JavaScript
const response = await fetch('/api/users/user_123');
const user = await response.json();
```

```python Python
import requests

response = requests.get('https://api.example.com/users/user_123')
user = response.json()
```

```bash cURL
curl https://api.example.com/users/user_123 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

</CodeGroup>

<ResponseExample>

```json 200 Success
{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2025-10-16T12:00:00Z"
}
```

```json 404 Not Found
{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}
```

```json 403 Forbidden
{
  "error": "Insufficient permissions",
  "code": "FORBIDDEN"
}
```

</ResponseExample>

## Create User

<div className="api-method">
  <div className="api-method-label">POST</div>
  <div className="api-method-path">/api/users</div>
</div>

Creates a new user account.

### Request Body

<ParamField body="email" type="string" required>
  User's email address (must be unique)
</ParamField>

<ParamField body="name" type="string" required>
  Display name
</ParamField>

<ParamField body="password" type="string" required>
  Account password (min 8 characters)
</ParamField>

### Response

<ResponseField name="user" type="User">
  The created user object
</ResponseField>

### Error Codes

<ResponseField name="400" type="ValidationError">
  Input validation failed
</ResponseField>

<ResponseField name="409" type="ConflictError">
  Email address already exists
</ResponseField>

<CodeGroup>

```typescript TypeScript SDK
import { createUser } from '@/api/users';

const newUser = await createUser({
  email: 'user@example.com',
  name: 'John Doe',
  password: 'secure-password'
});
```

```javascript JavaScript
const response = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    name: 'John Doe',
    password: 'secure-password'
  })
});
const user = await response.json();
```

</CodeGroup>

<Tip>
  Passwords are automatically hashed using Argon2 before storage. Never log or expose raw passwords.
</Tip>
```

### Quickstart Guide Generation

**Command:**
```
/mintlify-docs --quickstart --from-code=src/ "Getting started with our authentication system"
```

**Generated Documentation:**
```mdx
---
title: 'Quickstart'
description: 'Get started with authentication in 5 minutes'
icon: 'rocket'
---

# Getting Started

This guide will help you integrate authentication into your application in under 5 minutes.

<Steps>

<Step title="Install the SDK">
  Install the authentication package using your preferred package manager:

  <CodeGroup>

  ```bash npm
  npm install @yourapp/auth
  ```

  ```bash pnpm
  pnpm add @yourapp/auth
  ```

  ```bash yarn
  yarn add @yourapp/auth
  ```

  </CodeGroup>
</Step>

<Step title="Configure Environment Variables">
  Add your API credentials to your `.env` file:

  ```bash .env
  AUTH_SECRET=your-secret-key
  AUTH_URL=https://api.yourapp.com
  GITHUB_CLIENT_ID=your-github-client-id
  GITHUB_CLIENT_SECRET=your-github-client-secret
  ```

  <Warning>
    Never commit your `.env` file to version control. Add it to `.gitignore`.
  </Warning>
</Step>

<Step title="Initialize the Client">
  Create an authentication client instance:

  ```typescript lib/auth.ts
  import { createAuthClient } from '@yourapp/auth';

  export const auth = createAuthClient({
    secret: process.env.AUTH_SECRET!,
    baseUrl: process.env.AUTH_URL!,
    providers: {
      github: {
        clientId: process.env.GITHUB_CLIENT_ID!,
        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      },
    },
  });
  ```
</Step>

<Step title="Add Authentication to Your App">
  Wrap your application with the authentication provider:

  ```typescript app/layout.tsx
  import { AuthProvider } from '@yourapp/auth/react';
  import { auth } from '@/lib/auth';

  export default function RootLayout({ children }) {
    return (
      <html>
        <body>
          <AuthProvider client={auth}>
            {children}
          </AuthProvider>
        </body>
      </html>
    );
  }
  ```
</Step>

<Step title="Use Authentication Hooks">
  Access authentication state in your components:

  ```typescript components/profile.tsx
  'use client';

  import { useAuth } from '@yourapp/auth/react';

  export function UserProfile() {
    const { user, signIn, signOut } = useAuth();

    if (!user) {
      return (
        <button onClick={() => signIn('github')}>
          Sign in with GitHub
        </button>
      );
    }

    return (
      <div>
        <p>Welcome, {user.name}!</p>
        <button onClick={signOut}>Sign out</button>
      </div>
    );
  }
  ```
</Step>

</Steps>

## Next Steps

<CardGroup cols={2}>

<Card title="API Reference" icon="code" href="/api-reference">
  Explore the complete API documentation
</Card>

<Card title="Authentication Guide" icon="shield" href="/guides/authentication">
  Learn about advanced authentication patterns
</Card>

<Card title="Security Best Practices" icon="lock" href="/guides/security">
  Implement security best practices
</Card>

<Card title="Examples" icon="lightbulb" href="/examples">
  View example implementations
</Card>

</CardGroup>
```

### OpenAPI to Documentation

**Command:**
```
/mintlify-docs --api-reference --from-openapi=openapi.yaml
```

**Generated mint.json Configuration:**
```json
{
  "$schema": "https://mintlify.com/schema.json",
  "name": "Your API Documentation",
  "logo": {
    "dark": "/logo/dark.svg",
    "light": "/logo/light.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },
  "topbarLinks": [
    {
      "name": "Support",
      "url": "mailto:support@example.com"
    }
  ],
  "topbarCtaButton": {
    "name": "Dashboard",
    "url": "https://dashboard.example.com"
  },
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference"
    },
    {
      "name": "Guides",
      "url": "guides"
    }
  ],
  "anchors": [
    {
      "name": "Documentation",
      "icon": "book-open-cover",
      "url": "https://docs.example.com"
    },
    {
      "name": "Community",
      "icon": "discord",
      "url": "https://discord.gg/example"
    },
    {
      "name": "GitHub",
      "icon": "github",
      "url": "https://github.com/example/repo"
    }
  ],
  "navigation": [
    {
      "group": "Get Started",
      "pages": [
        "introduction",
        "quickstart",
        "development"
      ]
    },
    {
      "group": "API Reference",
      "pages": [
        "api-reference/authentication",
        "api-reference/users",
        "api-reference/organizations"
      ]
    }
  ],
  "footerSocials": {
    "twitter": "https://twitter.com/example",
    "github": "https://github.com/example",
    "linkedin": "https://www.linkedin.com/company/example"
  },
  "analytics": {
    "posthog": {
      "apiKey": "phc_xxx"
    }
  },
  "api": {
    "baseUrl": "https://api.example.com",
    "auth": {
      "method": "bearer"
    }
  }
}
```

## Interactive Components

### Custom MDX Components
```mdx
<Accordion title="How does authentication work?">
  Our authentication system uses JWT tokens with automatic refresh. Sessions last 7 days by default.
</Accordion>

<Info>
  All API requests must include a valid Bearer token in the Authorization header.
</Info>

<Warning>
  Never expose your API secret key in client-side code.
</Warning>

<Tip>
  Use environment variables to manage different API keys for development and production.
</Tip>

<Check>
  Your API credentials are correctly configured!
</Check>
```

## Best Practices

1. **Clear Structure**: Organize documentation with logical navigation
2. **Code Examples**: Include examples in multiple languages
3. **Error Documentation**: Document all possible error codes and responses
4. **Interactive Elements**: Use Mintlify components for better UX
5. **Version Management**: Maintain docs for multiple API versions
6. **Search Optimization**: Use descriptive titles and descriptions
7. **Regular Updates**: Keep documentation in sync with code changes