Hue: {hue}° setHue(Number.parseInt(e.target.value))} className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1" /> Saturation: {saturation}% setSaturation(Number.parseInt(e.target.value))} className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1" /> Lightness: {lightness}% setLightness(Number.parseInt(e.target.value))} className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1" />

{colors.map((color, idx) => (

copyToClipboard(color)} /> ))}

Base color: hsl({hue}, {saturation}%, {lightness}%)

) } ``` Import the `ColorGenerator` component and use it in an MDX file: ```mdx theme={null} import { ColorGenerator } from "/snippets/color-generator.jsx" ``` The color generator renders as an interactive React component with sliders to adjust hue, saturation, and lightness. ## Considerations React hook components render on the client-side, which has several implications: * **SEO**: Search engines might not fully index dynamic content. * **Initial load**: Visitors may experience a flash of loading content before components render. * **Accessibility**: Ensure dynamic content changes are announced to screen readers. * **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays. * **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations. * **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders. * **Lazy loading**: Consider lazy loading complex components to improve initial page load time. When building React components for documentation, prioritize accessibility by using semantic HTML, ARIA labels, and keyboard navigation support. # Themes Source: https://mintlify-docs.mintlify.app/customize/themes Choose the appearance of your documentation with pre-built themes. Customize the appearance of your documentation by selecting from a variety of professionally designed themes. Each theme offers distinct visual aesthetics and layouts to match your brand and content style. ## Configuring themes Set your theme in `docs.json` using the [theme](/organize/settings#param-theme) configuration property: ```json docs.json theme={null} { "theme": "mint" } ``` ## Available themes Mintlify offers nine professionally designed themes, each with unique aesthetics and navigation patterns: Classic documentation theme with time-tested layouts and familiar navigation. Modern, clean aesthetics perfect for AI and SaaS products. Sophisticated fintech theme with deep customization for enterprise documentation. Stripped-back essentials for distraction-free documentation. Retro terminal vibes with monospace fonts for that 80s hacker aesthetic. Card-based organization meets minimalist design for intuitive navigation. Modern documentation crafted for complex navigation and custom components. Minimal, elegant layouts designed for large-scale content-focused documentation. Clean, minimal design for polished documentation. ## Preview themes Click on any theme card above to preview it in action. Each preview link showcases the theme's navigation structure, typography, color palette, and overall visual design. Choose a theme that complements your brand identity and matches your documentation's complexity level. Enterprise products may benefit from Palm, while developer tools might prefer Linden or Mint. # Authentication setup Source: https://mintlify-docs.mintlify.app/deploy/authentication-setup Control access to your documentation by authenticating users. [Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication. [Enterprise plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods. Authentication requires users to log in before accessing your documentation. When you enable authentication, users must log in to access any content. You can configure specific pages or groups as public while keeping other pages protected. ## Configure authentication Select the handshake method that you want to configure. Password authentication provides access control only and does **not** support user-specific features like group-based access control or API playground pre-filling. ### Prerequisites * Your security requirements allow sharing passwords among users. ### Set up 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Enable authentication. 3. In the **Password Protection** section, enter a secure password After you enter a password, your site redeploys. When it finishes deploying, anyone who visits your site must enter the password to access your content. Securely share the password and documentation URL with authorized users. ### Example You host your documentation at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple. **Create a strong password** in your dashboard. **Share credentials** with authorized users. ### Prerequisites * Everyone who needs to access your documentation must be a member of your Mintlify organization. ### Set up 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Enable authentication. 3. In the **Custom Authentication** section, click **Mintlify Auth**. 4. Click **Enable Mintlify Auth**. After you enable Mintlify authentication, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your Mintlify organization to access your content. 1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members). 2. Add each person who should have access to your documentation. 3. Assign appropriate roles based on their editing permissions. ### Example You host your documentation at `docs.foo.com` and your entire team has access to your dashboard. You want to restrict access to team members only. **Enable Mintlify authentication** in your dashboard settings. **Verify team access** by checking that all team members are active in your organization. ### Prerequisites * An OAuth or OIDC server that supports the Authorization Code Flow. * Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable group-based access control). ### Set up 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Enable authentication. 3. In the **Custom Authentication** section, click **OAuth**. 4. Configure these fields: * **Authorization URL**: Your OAuth endpoint. * **Client ID**: Your OAuth 2.0 client identifier. * **Client Secret**: Your OAuth 2.0 client secret. * **Scopes** (optional): Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels. * **Additional authorization parameters** (optional): Additional query parameters to add to the initial authorization request. * **Token URL**: Your OAuth token exchange endpoint. * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Required for group-based access control. If omitted, the OAuth flow only verifies identity. * **Logout URL** (optional): The native logout URL for your OAuth provider. When users log out, Mintlify validates the logout redirect against this configured URL for security. The redirect only succeeds if it exactly matches the configured `logoutUrl`. If you do not configure a logout URL, users redirect to `/login`. Mintlify redirects users with a `GET` request and does not append query parameters, so include any parameters (for example, `returnTo`) directly in the URL. * **Redirect URL** (optional): The URL to redirect users to after authentication. 5. Click **Save changes**. After you configure your OAuth settings, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your OAuth provider to access your content. 1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/products/authentication). 2. Add the redirect URL as an authorized redirect URL for your OAuth server. To enable group-based access control, create an API endpoint that: * Responds to `GET` requests. * Accepts an `Authorization: Bearer ` header for authentication. * Returns user data in the `User` format. See [User data format](#user-data-format) for more information. Mintlify calls this endpoint with the OAuth access token to retrieve user information. No additional query parameters are sent. Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/products/authentication). ### Example You host your documentation at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow. **Configure your OAuth server details** in your dashboard: * **Authorization URL**: `https://auth.foo.com/authorization` * **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` * **Scopes**: `['provider.users.docs']` * **Token URL**: `https://auth.foo.com/exchange` * **Info API URL**: `https://api.foo.com/docs/user-info` * **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs` **Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope, and returns: ```json theme={null} { "groups": ["engineering", "admin"], "expiresAt": 1735689600, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" } } } ``` Control session length with the `expiresAt` field in your user info response. This is a Unix timestamp (seconds since epoch) indicating when the session should expire. See [User data format](#user-data-format) for more details. **Configure your OAuth server to allow redirects** to your callback URL. ### Prerequisites * An authentication system that can generate and sign JWTs. * A backend service that can create redirect URLs. ### Set up 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/products/authentication). 2. Enable authentication. 3. In the **Custom Authentication** section, click **JWT**. 4. Enter the URL of your existing login flow. 5. Click **Save changes**. 6. Click **Generate new key**. 7. Store your key securely where it can be accessed by your backend. After you generate a private key, your site redeploys. When it finishes deploying, anyone who visits your site must log in to your JWT authentication system to access your content. Modify your existing login flow to include these steps after user authentication: * Create a JWT containing the authenticated user's info in the `User` format. See [User data format](#user-data-format) for more information. * Sign the JWT with your secret key, using the EdDSA algorithm. * Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash. ### Example You host your documentation at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard). Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication. After verifying user credentials: * Generate a JWT with user data in Mintlify's format. * Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`. ```ts TypeScript theme={null} import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration groups: res.locals.user.groups, apiPlaygroundInputs: { header: { "Authorization": `Bearer ${res.locals.user.apiKey}`, }, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'EdDSA' }) .setExpirationTime('10 s') // 10 second JWT expiration .sign(signingKey); return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); } ``` ```python Python theme={null} import jwt # pyjwt import os from datetime import datetime, timedelta from fastapi.responses import RedirectResponse private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '') @router.get('/auth') async def return_mintlify_auth_status(current_user): jwt_token = jwt.encode( payload={ 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session expiration 'groups': ['admin'] if current_user.is_admin else [], 'apiPlaygroundInputs': { 'header': { 'Authorization': f'Bearer {current_user.api_key}', }, }, }, key=private_key, algorithm='EdDSA' ) return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302) ``` ### Redirect unauthenticated users When an unauthenticated user tries to access a protected page, the redirect to your login URL preserves the user's intended destination. 1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`. 2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`. 3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`. 4. User lands in their original destination. ## Make pages public When using authentication, all pages require authentication to access by default. You can make specific pages viewable without authentication at the page or group level with the `public` property. ### Individual pages To make a page public, add `public: true` to the page's frontmatter. ```mdx Public page example theme={null} --- title: "Public page" public: true --- ``` ### Groups of pages To make all pages in a group public, add `"public": true` beneath the group's name in the `navigation` object of your `docs.json`. ```json Public group example theme={null} { "navigation": { "groups": [ { "group": "Public group", "public": true, "icon": "play", "pages": [ "quickstart", "installation", "settings" ] }, { "group": "Private group", "icon": "pause", "pages": [ "private-information", "secret-settings" ] } ] } } ``` ## Control access with groups When you use OAuth or JWT authentication, you can restrict specific pages to certain user groups. This is useful when you want different users to see different content based on their role or attributes. Manage groups through user data passed during authentication. See [User data format](#user-data-format) for details. ```json Example user info theme={null} { "groups": ["admin", "beta-users"], "expiresAt": 1735689600 } ``` Specify which groups can access specific pages using the `groups` property in frontmatter. ```mdx Example page restricted to the admin group highlight={3} theme={null} --- title: "Admin dashboard" groups: ["admin"] --- ``` Users must belong to at least one of the listed groups to access the page. If a user tries to access a page without the required group, they'll receive a 404 error. ### How groups interact with public pages * All pages require authentication by default. * Pages with a `groups` property are only accessible to authenticated users in those groups. * Pages without a `groups` property are accessible to all authenticated users. * Pages with `public: true` and no `groups` property are accessible to everyone. ```mdx Public page theme={null} --- title: "Public guide" public: true --- ``` ```mdx Protected page theme={null} --- title: "API reference" --- ``` ```mdx Protected page with groups theme={null} --- title: "Advanced configurations" groups: ["pro", "enterprise"] --- ``` ## User data format When using OAuth or JWT authentication, your system returns user data that controls session length, group membership, and [content personalization](/create/personalization). ```tsx Format theme={null} type User = { expiresAt?: number; groups?: string[]; content?: Record; apiPlaygroundInputs?: { server?: Record; header?: Record; query?: Record; cookie?: Record; path?: Record; }; }; ``` ```json Example theme={null} { "expiresAt": 1735689600, "groups": ["admin", "beta-users"], "content": { "firstName": "Jane", "company": "Acme Corp" }, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" }, "server": { "baseUrl": "https://api.foo.com" } } } ``` Session expiration time in seconds since epoch. When the current time passes this value, the user must re-authenticate. **For JWT:** This differs from the JWT's `exp` claim, which determines when a JWT is considered invalid. Set the JWT `exp` claim to a short duration (10 seconds or less) for security. Use `expiresAt` for the actual session length (hours to weeks). List of groups the user belongs to. Pages with matching `groups` in their frontmatter are accessible to this user. **Example**: A user with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups. Custom data accessible in MDX pages via the `user` variable for [personalized content](/create/personalization#dynamic-mdx-content). Pre-fills API playground fields with user-specific values. When a user authenticates, these values populate the corresponding input fields in the API playground. Users can override pre-filled values, and their overrides persist in local storage. Only values that match the current endpoint's security scheme are applied. Header values to pre-fill, keyed by header name. Query parameter values to pre-fill, keyed by parameter name. Cookie values to pre-fill, keyed by cookie name. Server variable values to pre-fill, keyed by variable name. Path parameter values to pre-fill, keyed by parameter name. # Deployments Source: https://mintlify-docs.mintlify.app/deploy/deployments Manage deployments, view history, and monitor status. Your documentation site automatically deploys when you push changes to your connected repository. This requires the Mintlify GitHub app to be properly installed and connected. If your latest changes are not appearing on your live site, first check that the GitHub account or organization that owns your docs repository has the GitHub App installed. See [GitHub troubleshooting](/deploy/github#troubleshooting) for more information. If you have the GitHub App installed, but changes are still not deploying, manually trigger a deployment from your dashboard. ## Manually trigger a deployment Check that your latest commit appears in your docs repository and did not encounter any errors. Go to your [dashboard](https://dashboard.mintlify.com) and select the deploy button. The manual update button emphasized with an orange rectangle.

The manual update button emphasized with an orange rectangle.

## Delete a deployment You can permanently delete a deployment from the [Danger zone](https://dashboard.mintlify.com/settings/organization/danger-zone) in your dashboard settings. This action is irreversible and removes all deployment data, including any associated preview deployments. Go to the [Danger zone](https://dashboard.mintlify.com/settings/organization/danger-zone) in the settings page of your dashboard. 1. In the **Delete my deployment** section, provide a reason for deletion. 2. Click the delete button and confirm that you want to delete the deployment. Deleting a deployment is permanent and cannot be undone. If you have an active subscription, you'll receive a prorated credit for any unused time remaining in your billing period. If you have multiple deployments, you'll be redirected to another deployment after deletion. If you delete your only deployment, you'll be redirected to the Mintlify homepage. When you delete a deployment, the organization admin receives an email notification confirming the deletion. # GitHub Source: https://mintlify-docs.mintlify.app/deploy/github Connect to a GitHub repository for automated deployments, pull request previews, and continuous synchronization. Mintlify uses a GitHub App to automatically sync your documentation with your GitHub repository. **Do you need the GitHub App?** * **Mintlify-hosted repository** in the `mintlify-community` organization: No. The GitHub App is already configured. * **Your own repository**: Yes. Install the GitHub App to enable automatic deployments when you push changes. See your repository in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard. If your repository is in a private repository owned by the Mintlify organization, the GitHub App is automatically configured and managed by Mintlify. You can use the web editor to make changes to your documentation. If you want to work on your documentation locally, clone the repository to your own organization and update your Git settings to use your own repository. ## Clone to your own repository If you skipped connecting your own Git repository during onboarding, your documentation lives in a private repository owned by the Mintlify organization. To move it to your own account or organization: 1. Go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard. 2. Download your documentation as a zip file. 3. Create a new repository on GitHub or GitLab. 4. Extract the zip contents and push them to your new repository. 5. Return to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and connect your new repository to Mintlify. 6. Install the GitHub App by following the steps in [Install the GitHub App](#install-the-github-app) below. ## Install the GitHub App You must have organization ownership or administrator permissions in a repository to install the app. If you lack the necessary permissions, the repository owner must approve the installation request. Install the Mintlify GitHub App through your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app). We recommend only granting access to your documentation repository. Mintlify GitHub App installation page with the 'Only select repositories' option selected.

Mintlify GitHub App installation page with the 'Only select repositories' option selected.

## Permissions When you install the GitHub App, grant the following permissions. Read permissions: * `metadata`: Basic repository information Read and write permissions: * `checks`: Create status checks on pull requests * `code`: Read file changes when you commit to your docs branch * `deployments`: Generate preview deployments for pull requests * `pull requests`: Create branches and pull requests from the web editor The app only accesses repositories that you explicitly grant it access to. If you have branch protection rules enabled, the app can't push directly to protected branches. ## Manage repository access When installing the GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to your documentation repository and any repositories that you want to provide as context for the agent. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new). ## Configure docs source Change the organization, repository, or branch that your documentation builds from in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) section of your dashboard. ## GitHub Enterprise with IP allowlists If your GitHub Enterprise Cloud organization has an IP allowlist enabled, you need to add Mintlify's egress IP address (`54.242.90.151`) to your allowlist for the GitHub App to function properly. Follow [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) to configure your IP allowlist. ## Troubleshooting ### Deployment not triggering automatically If pushes to your repository don't trigger deployments, check the following possible problems. Check that the correct repository has the app installed. 1. Go to [GitHub App settings](https://dashboard.mintlify.com/settings/organization/github-app) in your dashboard. 2. Check that your repository is on the active app installations list. Ensure that you're pushing to the correct branch. 1. Go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 2. Verify the branch in your dashboard matches the branch that you're pushing to. ### GitHub App connection issues If you encounter problems with the GitHub app, resetting the connection can solve most problems. 1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**. 2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app. 1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app. 2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard. ### Feedback add-ons are unavailable The edit suggestions and raise issues feedback features are only available for public GitHub repositories. If these options are disabled in your dashboard, check your repository visibility. If your repository is public and you cannot enable the edit suggestions or raise issues options in your dashboard, revalidate your Git settings. Go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard. Click the green check mark in the corner of the Git settings box to revalidate your repository settings. This forces an update to your repository settings to reflect whether your repository is public or private. The Git Settings page in the Mintlify dashboard. An orange arrow points to the green check mark that revalidates the repository settings.

The Git Settings page in the Mintlify dashboard. An orange arrow points to the green check mark that revalidates the repository settings.

# Preview deployments Source: https://mintlify-docs.mintlify.app/deploy/preview-deployments Get unique preview URLs for pull requests to review changes before merging. Preview deployments are available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=preview-deployments). Preview deployments let you see how changes to your docs look before merging to production. Each preview creates a shareable URL that updates automatically as you push new changes. Preview URLs are publicly viewable by default. Share a preview link with anyone who needs to review your changes. ## Create preview deployments Preview deployments are created automatically through pull requests or manually from your dashboard. ### Automatic previews Automatic previews are only created for pull requests targeting your [deployment branch](/guides/git-concepts#deployment-branch). When you create a pull request, the Mintlify bot automatically adds a link to view the preview deployment in your pull request. The preview updates each time you push new commits to the branch. Link to view deployment in the pull request timeline

Link to view deployment in the pull request timeline

### Manual previews You can manually create a preview for any branch. 1. Go to your [dashboard](https://dashboard.mintlify.com/). 2. Select **Previews**. 3. Select **Create custom preview**. 4. Enter the name of the branch you want to preview. 5. Select **Create deployment**. ## Redeploy a preview Redeploy a preview to refresh content or retry after a failed deployment. 1. Select the preview from your [dashboard](https://dashboard.mintlify.com/). 2. Select **Redeploy**. The Previews menu with the deploy button emphasized by an orange rectangle.

The Previews menu with the deploy button emphasized by an orange rectangle.

## Preview widget The preview widget appears on preview deployments to help you navigate and review updated pages. The widget is a floating button in the bottom-right corner of your preview deployment. Preview widget expanded to show list of changed files.

Preview widget expanded to show list of changed files.

1. Click the widget to show all added, modified, or removed files in the preview. 2. Click a file to view the changes on the corresponding page. 3. Use the search bar to filter the list of changed files. The widget only appears on preview deployments, not on your live site or local previews. ## Restrict access to preview deployments By default, preview deployments are publicly accessible to anyone with the URL. You can restrict access to authenticated members of your Mintlify organization. 1. Navigate to the **Previews** section in the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard. 2. Click the **Preview authentication** toggle to enable or disable preview authentication. The preview authentication toggle in the Add-ons page

The preview authentication toggle in the Add-ons page

## Troubleshooting preview deployments If your preview deployment fails, try these troubleshooting steps. * **View the build logs**: In your [dashboard](https://dashboard.mintlify.com/), go to **Previews** and click the failed preview. The deployment logs show errors that caused failures. * **Check your configuration**: * Invalid `docs.json` syntax * Missing or incorrect file paths referenced in your navigation * Invalid frontmatter in MDX files * Broken image links or missing image files * **Validate locally**: Run `mint dev` locally to catch build errors before pushing to the repository. * **Check recent changes**: Review the most recent commits in your branch to identify what changes caused the build to fail. # Web editor overview Source: https://mintlify-docs.mintlify.app/editor/index Edit and publish documentation in your browser. Decorative image in light mode

Create, edit, and publish documentation directly in your browser with the web editor. View and share previews of your changes; manage your site's navigation structure with drag-and-drop components; and publish updates using your team's preferred workflow. ## Key features * **Visual and Markdown editing**: Switch between visual and Markdown editing modes to suit your workflow. * **Live preview**: See real-time changes without creating a preview deployment. * **Shareable preview links**: Create preview links for your team from the editor. * **Drag-and-drop navigation**: Organize your site structure visually without editing configuration files. * **Git synchronization**: All changes sync automatically with your documentation repository. * **Team collaboration**: Multiple team members can work simultaneously with branch-based workflows. ## Get started Create, edit, and organize pages. Structure your site navigation. Upload and use images, videos, and other assets. Preview your site in real time as you edit. ## Publish and collaborate Save and publish your documentation updates. Work with teams using branches and pull requests. ## Reference Configure site branding, colors, and features. Speed up your workflow with keyboard shortcuts. # Accessibility Source: https://mintlify-docs.mintlify.app/guides/accessibility Create documentation that as many people as possible can use with WCAG compliance. When you create accessible documentation, you prioritize content design that makes your documentation usable by as many people as possible regardless of how they access and interact with your documentation. Accessible documentation improves the user experience for everyone. Your content is more clear, better structured, and easier to navigate. This guide offers some best practices for creating accessible documentation, but it is not exhaustive. You should consider accessibility an ongoing process. Technologies and standards change over time, which introduce new opportunities to improve documentation. ## What is accessibility? Accessibility (sometimes abbreviated as a11y for the number of letters between the first and last letters of "accessibility") is intentionally designing and building websites and tools that as many people as possible can use. People with temporary or permanent disabilities should have the same level of access to digital technologies. And designing for accessibility benefits everyone, including people who access your website on mobile devices or slow networks. Accessible documentation follows web accessibility standards, primarily the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG22/quickref/). These guidelines help ensure your content is perceivable, operable, understandable, and robust. ## Getting started with accessibility Making your documentation accessible is a process. You don't have to fix everything all at once and you can't do it only once. If you're just beginning to implement accessibility practices for your documentation, consider a phased approach where you start with high-impact changes and build from there. ### First steps Here are three things you can do right now to improve the accessibility of your documentation: 1. **Run `mint a11y`** to identify accessibility issues in your content. 2. **Add alt text** to all images. 3. **Check your heading hierarchy** to ensure one H1 per page and headings follow sequential order. ### Plan your accessibility work The best workflow is the one that works for your team. Here is one way that you can approach accessibility work: **Phase 1: Images and structure** * Review all images for descriptive alt text. * Audit link text and replace generic phrases like "click here." * Fix heading hierarchy issues across your documentation. **Phase 2: Navigation and media** * Test keyboard navigation on your documentation. * Test screen reader support. * Add captions and transcripts to embedded videos. * Review color contrast. **Phase 3: Build it into your workflow** * Run `mint a11y` before publishing new content. * Include accessibility checks in your content review process. * Test keyboard navigation when adding interactive features. * Verify new external links and embeds include proper titles and descriptions. Starting small and building accessibility into your regular workflow makes it sustainable. Each improvement helps more users access your documentation successfully. ## Structure your content Well-structured content is easier to navigate and understand, especially for screen reader users who rely on headings to move through pages and people who use keyboard navigation. ### Use proper heading hierarchy Each page should have a single H1 heading, which is defined by the `title:` property in a page's frontmatter. Use additional headings in order without skipping. For example, don't skip from H2 to H4. ```mdx theme={null} # Page title (H1) ## Main section (H2) ### Subsection (H3) ### Another subsection (H3) ## Another main section (H2) # Page title (H1) ## Main section (H2) #### Subsection (H4) ### Another subsection (H3) ``` Headings at the same level should have unique names. ```mdx theme={null} ## Accessibility tips (H2) ### Write effective alt text (H3) ### Use proper color contrast (H3) ## Accessibility tips (H2) ### Tip (H3) ### Tip (H3) ``` ### Write descriptive link text Link text should be meaningful and connected to the destination. Avoid vague phrases like "click here" or "read more." ```mdx theme={null} Learn how to [configure your navigation](/organize/navigation). [Learn more](/organize/navigation). ``` ### Keep content scannable * Break up long paragraphs. * Use lists for steps and options. * Highlight information with callouts. ### Use proper table structure Use tables sparingly and only for tabular data that has meaning inherited from the column and row headers. When using tables, include headers so screen readers can associate data with the correct column: ```mdx theme={null} | Feature | Status | | ------- | ------ | | Search | Active | | Analytics | Active | ``` ## Write descriptive alt text Alt text makes images accessible to screen reader users and appears when images fail to load. Images in your documentation should have alt text that describes the image and makes it clear why the image is included. Even with alt text, you should not rely on images alone to convey information. Make sure your content describes what the image communicates. ### Write effective alt text * **Be specific**: Describe what the image shows, not just that it's an image. * **Be concise**: Aim for one to two sentences. * **Avoid redundancy**: Don't start with "Image of" because screen readers already know that the alt text is associated with an image. However, you should include descriptions like "Screenshot of" or "Diagram of" if that context is important to the image. ```mdx theme={null} ![Screenshot of the dashboard showing three active projects and two pending invitations](/images/dashboard.png) ![Dashboard screenshot](/images/dashboard.png) ``` ### Add alt text to images For Markdown images, include alt text in the square brackets: ```mdx theme={null} ![Description of the image](/path/to/image.png) ``` For HTML images, use the `alt` attribute: ```html theme={null} Settings panel with accessibility options enabled. The options are emphasized with an orange rectangle.

Settings panel with accessibility options enabled. The options are emphasized with an orange rectangle.

``` ### Add titles to embedded content Iframes and video embeds require descriptive titles: ```html theme={null} ``` ## Design for readability Visual design choices affect how accessible your documentation is to users with low vision, color blindness, or other visual disabilities. ### Ensure sufficient color contrast If you customize your theme colors, verify the contrast ratios meet WCAG requirements: * Body text: minimum 4.5:1 contrast ratio * Large text: minimum 3:1 contrast ratio * Interactive elements: minimum 3:1 contrast ratio Test both light and dark mode. The `mint a11y` command checks for color contrast. ### Don't rely on color alone If you use color to convey information, include a text label or icon as well. For example, don't mark errors only with red text. Include an error icon or the word "Error." ### Use clear, concise language * Write in plain language. * Define technical terms when first used. * Avoid run-on sentences. * Use active voice. ## Make code examples accessible Code blocks are a core part of technical documentation, but they require specific accessibility considerations to ensure screen reader users can understand them. In general, follow these guidelines: * Break long code examples into smaller, logical chunks. * Comment complex logic within the code. * Consider providing a text description for complex algorithms. * When showing file structure, use actual code blocks with language labels rather than ASCII art. ### Specify the programming language Always declare the language for syntax highlighting. This helps screen readers announce the code context to users: ````mdx theme={null} ```javascript function getUserData(id) { return fetch(`/api/users/${id}`); } ``` ```` ### Provide context around code Provide clear context for code blocks: ````mdx theme={null} The following function fetches user data from the API: ```javascript function getUserData(id) { return fetch(`/api/users/${id}`); } ``` This returns a promise that resolves to the user object. ```` ## Video and multimedia accessibility Videos, animations, and other multimedia content need text alternatives so all users can access the information they contain. ### Add captions to videos Captions make video content accessible to users who are deaf or hard of hearing. They also help users in sound-sensitive environments and non-native speakers: * Use captions for all spoken content in videos. * Include relevant sound effects in captions. * Ensure captions are synchronized with the audio. * Use proper punctuation and speaker identification when multiple people speak. Most video hosting platforms support adding captions. Upload caption files or use auto-generated captions as a starting point, then review for accuracy. ### Provide transcripts Transcripts offer an alternative way to access video content. They're searchable, easier to reference, and accessible to screen readers: ```mdx theme={null} In this tutorial, we'll walk through setting up authentication... ``` Place transcripts near the video or provide a clear link to access them. ### Consider alternatives to video-only content If critical information only appears in a video: * Provide the same information in text form. * Include key screenshots with descriptive alt text. * Create a written tutorial that covers the same material. This ensures users who can't access video content can still complete their task. ## Test your documentation Regular testing helps you catch accessibility issues before users encounter them. ### Check for accessibility issues with `mint a11y` Use the `mint a11y` CLI command to automatically scan your documentation for common accessibility issues: ```bash theme={null} mint a11y ``` The command checks for: * Missing alt text on images and videos. * Insufficient color contrast. When the scan completes, review the reported issues and fix them in your content. Run the command again to verify your fixes. Use flags to check for specific accessibility issues. ```bash theme={null} # Check only for missing alt text mint a11y --skip-contrast # Check only for color contrast issues mint a11y --skip-alt-text ``` ### Basic keyboard navigation test Navigate through your documentation using only your keyboard: 1. Press Tab to move forward through interactive elements. 2. Press Shift + Tab to move backward. 3. Press Enter to activate links and buttons. 4. Verify all interactive elements are reachable and have visible focus indicators. ### Go deeper with accessibility testing For more comprehensive testing: * **Screen readers**: Test with [NVDA (Windows)](https://www.nvaccess.org/) or [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/). * **Browser extensions**: Install [axe DevTools](https://www.deque.com/axe/browser-extensions/) or [WAVE](https://wave.webaim.org/extension/) to scan pages for issues. * **WCAG guidelines**: Review the [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG22/quickref/) for detailed standards. ## Additional resources Continue learning about accessibility with these trusted resources: * **[WebAIM](https://webaim.org/)**: Practical articles and tutorials on web accessibility * **[The A11y Project](https://www.a11yproject.com/)**: Community-driven accessibility resources and checklist * **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**: Official accessibility standards and guidance # Claude Code Source: https://mintlify-docs.mintlify.app/guides/claude-code Configure Claude Code to write, review, and update your documentation. Claude Code is an agentic command line tool that can help you maintain your documentation. It can write new content, review existing pages, and keep docs up to date. You can train Claude Code to understand your documentation standards and workflows by adding a `CLAUDE.md` file to your project and refining it over time. ## Getting started **Prerequisites:** * Active Claude subscription (Pro, Max, or API access) **Setup:** 1. Install Claude Code: ```bash theme={null} npm install -g @anthropic-ai/claude-code ``` 2. Navigate to your docs directory. 3. (Optional) Add the `CLAUDE.md` file below to your project. 4. Run `claude` to start. ## CLAUDE.md template Save a `CLAUDE.md` file at the root of your docs directory to help Claude Code understand your project. This file trains Claude Code on your documentation standards, preferences, and workflows. See [Manage Claude's memory](https://docs.anthropic.com/en/docs/claude-code/memory) in the Anthropic docs for more information. Copy this example template or make changes for your docs specifications: ```mdx theme={null} # Mintlify documentation ## Working relationship - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so - ALWAYS ask for clarification rather than making assumptions - NEVER lie, guess, or make up anything ## Project context - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings - Components: Mintlify components ## 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 it is done for a strategic reason - Check existing patterns for consistency - Start by making the smallest reasonable changes ## docs.json - Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation ## Frontmatter requirements for pages - title: Clear, descriptive page title - description: Concise summary for SEO/navigation ## 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 ## Git workflow - NEVER use --no-verify when committing - Ask how to handle uncommitted changes before starting - Create a new branch when no clear branch exists for changes - Commit frequently throughout development - NEVER skip or disable pre-commit hooks ## Do not - Skip frontmatter on any MDX file - Use absolute URLs for internal links - Include untested code examples - Make assumptions - always ask for clarification ``` ## Sample prompts Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs. ### Convert notes to polished docs Turn rough drafts into proper Markdown pages with components and frontmatter. **Example prompt:** ```text wrap theme={null} Convert this text into a properly formatted MDX page: [paste your text here] ``` ### Review docs for consistency Get suggestions to improve style, formatting, and component usage. **Example prompt:** ```text wrap theme={null} Review the files in docs/ and suggest improvements for consistency and clarity ``` ### Update docs when features change Keep documentation current when your product evolves. **Example prompt:** ```text wrap theme={null} Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples ``` ### Generate comprehensive code examples Create multi-language examples with error handling. **Example prompt:** ```text wrap theme={null} Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling ``` ## Extending Claude Code Beyond manually prompting Claude Code, you can integrate it with your existing workflows. ### Automation with GitHub Actions Run Claude Code automatically when code changes to keep docs up to date. You can trigger documentation reviews on pull requests or update examples when API changes are detected. ### Multi-instance workflows Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss. ### Team collaboration Share your refined `CLAUDE.md` file with your team to ensure consistent documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process. ### Custom commands Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team. # Content types Source: https://mintlify-docs.mintlify.app/guides/content-types Choose the right content type for your documentation goals. This page explains different content types, when to use each one, and how to approach writing for each type. Documentation should be organized around the specific goal you're trying to help people achieve. ## Categorize using the Diátaxis framework The [Diátaxis framework](https://diataxis.fr) is a helpful guide for categorizing content based on your audience's needs. Documentation can generally be mapped into one of these types: 1. Tutorials: Learning-oriented content for new users 2. How-to guides: Task-oriented guidance for specific problems 3. Explanations: Understanding-oriented conceptual discussions 4. Reference: Information-oriented technical descriptions Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need. A diagram of the Diátaxis framework showing four quadrants that correspond to the four content types: Tutorials, How-To Guides, Reference, and Explanation.

A diagram of the Diátaxis framework showing four quadrants that correspond to the four content types: Tutorials, How-To Guides, Reference, and Explanation.

## Picking a type | Question | Tutorial | How-To | Reference | Explanation | | :------------------------------------- | :--------------------- | :----------------------- | :----------------------- | :---------------------- | | What is the user's goal? | Learn through practice | Solve a specific problem | Find precise information | Understand concepts | | What is the user's knowledge? | Beginner | Intermediate | Experienced | Any level | | What is the primary focus? | Learning by doing | Achieving a goal | Providing information | Deepening understanding | | How is the content structured? | Step-by-step | Problem-solution | Organized facts | Conceptual discussions | | Is it task-oriented? | Yes, guided tasks | Yes, specific tasks | No, informational | No, conceptual | | Is it designed for linear progression? | Yes | No | No | No | ## Writing for each type ### Tutorials (Learning-oriented) * **Audience goal**: Learn something new through step-by-step instructions. * **Characteristics**: Sequential and assumes no prior knowledge. * **Writing approach**: * Set expectations of what the user achieves after reading. * Use clear, incremental steps. Minimize choices that need to be made by the user. * Point out milestones along the way. * Minimize theory and focus on concrete actions. ### How-To Guides (Problem-oriented) * **Audience goal**: Perform a specific task correctly. * **Characteristics**: Goal-driven and assumes some prior knowledge. * **Writing approach**: * Write from the perspective of the user, not the product. * Describe a logical sequence and omit unnecessary details. * Minimize context beyond what is necessary. ### Reference (Information-oriented) * **Audience goal**: Find details about a product's features. * **Characteristics**: Unambiguous, product-focused, scannable. * **Writing approach**: * Be scannable and concise. * Prioritize consistency. * Avoid explanatory content. Focus on examples that are easy to copy and modify. ### Explanation (Understanding-oriented) * **Audience goal**: Expand general understanding of a concept or highly complex feature. * **Characteristics**: Theoretical, potentially opinionated, broad in scope. * **Writing approach**: * Provide background context, such as design decisions or technical constraints. * Acknowledge opinions and alternatives. * Draw connections to other areas in the product or industry. ## Tips and tricks 1. **Maintain purpose**: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing. 2. **Consider content freshness**: Regardless of content type, try to optimize for evergreen documentation. If something represents a moment in time of what a feature looks like on a specific date, it's probably better suited for a changelog or blog post than in your documentation. Or if something changes very frequently avoid putting it in your docs. 3. **Think like your users**: Consider different user personas when organizing content. See [Understand your audience](/guides/understand-your-audience) for more information. 4. **Use templates**: Start with [content templates](/guides/content-templates) that provide the basic structure for each content type. While the Diátaxis framework provides a starting point, successful documentation requires contextual adaptation to your product. Start by understanding the framework's principles, then adjust them to serve your users' needs. ## Related pages Copy and modify templates for each content type. Write effective documentation with consistent style. Research and define your documentation audience. Organize your documentation structure effectively. Use data and metrics to improve documentation. # Cursor Source: https://mintlify-docs.mintlify.app/guides/cursor Configure Cursor to be your writing assistant. Transform Cursor into a documentation expert that knows your components, style guide, and best practices. ## Use Cursor with Mintlify Cursor rules provide persistent context about your documentation, ensuring more consistent suggestions that fit your standards and style. * **Project rules** are stored in your documentation repository and shared with your team. * **User rules** apply to your personal Cursor environment. We recommend creating project rules for your docs so that all contributors have access to the same rules. Create rules files in the `.cursor/rules` directory of your docs repo. See the [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions. ## Example project rule This rule provides Cursor with context to properly format Mintlify components and follow technical writing best practices. You can use this example as-is or customize it for your documentation: * **Writing standards**: Update language guidelines to match your style guide. * **Component patterns**: Add project-specific components or modify existing examples. * **Code examples**: Replace generic examples with real API calls and responses for your product. * **Style and tone preferences**: Adjust terminology, formatting, and other rules. Add this rule with any modifications as an `.mdc` file in the `.cursor/rules` directory of your docs repo. ````mdx wrap theme={null} # Mintlify technical writing rule You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. ## Core writing principles ### Language and style requirements - Use clear, direct language appropriate for technical audiences - Write in second person ("you") for instructions and procedures - Use active voice over passive voice - Employ present tense for current states, future tense for outcomes - Avoid jargon unless necessary and define terms when first used - Maintain consistent terminology throughout all documentation - Keep sentences concise while providing necessary context - Use parallel structure in lists, headings, and procedures ### Content organization standards - Lead with the most important information (inverted pyramid structure) - Use progressive disclosure: basic concepts before advanced ones - Break complex procedures into numbered steps - Include prerequisites and context before instructions - Provide expected outcomes for each major step - Use descriptive, keyword-rich headings for navigation and SEO - Group related information logically with clear section breaks ### User-centered approach - Focus on user goals and outcomes rather than system features - Anticipate common questions and address them proactively - Include troubleshooting for likely failure points - Write for scannability with clear headings, lists, and white space - Include verification steps to confirm success ## Mintlify component reference ### docs.json - Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation ### Callout components #### Note - Additional helpful information Supplementary information that supports the main content without interrupting flow #### Tip - Best practices and pro tips Expert advice, shortcuts, or best practices that enhance user success #### Warning - Important cautions Critical information about potential issues, breaking changes, or destructive actions #### Info - Neutral contextual information Background information, context, or neutral announcements #### Check - Success confirmations Positive confirmations, successful completions, or achievement indicators ### Code components #### Single code block Example of a single code block: ```javascript config.js const apiConfig = { baseURL: 'https://api.example.com', timeout: 5000, headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` } }; ``` #### Code group with multiple languages Example of a code group: ```javascript Node.js const response = await fetch('/api/endpoint', { headers: { Authorization: `Bearer ${apiKey}` } }); ``` ```python Python import requests response = requests.get('/api/endpoint', headers={'Authorization': f'Bearer {api_key}'}) ``` ```curl cURL curl -X GET '/api/endpoint' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` #### Request/response examples Example of request/response documentation: ```bash cURL curl -X POST 'https://api.example.com/users' \ -H 'Content-Type: application/json' \ -d '{"name": "John Doe", "email": "john@example.com"}' ``` ```json Success { "id": "user_123", "name": "John Doe", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z" } ``` ### Structural components #### Steps for procedures Example of step-by-step instructions: Run `npm install` to install required packages. Verify installation by running `npm list`. Create a `.env` file with your API credentials. ```bash API_KEY=your_api_key_here ``` Never commit API keys to version control. #### Tabs for alternative content Example of tabbed content: ```bash brew install node npm install -g package-name ``` ```powershell choco install nodejs npm install -g package-name ``` ```bash sudo apt install nodejs npm npm install -g package-name ``` #### Accordions for collapsible content Example of accordion groups: - **Firewall blocking**: Ensure ports 80 and 443 are open - **Proxy configuration**: Set HTTP_PROXY environment variable - **DNS resolution**: Try using 8.8.8.8 as DNS server ```javascript const config = { performance: { cache: true, timeout: 30000 }, security: { encryption: 'AES-256' } }; ``` ### Cards and columns for emphasizing information Example of cards and card groups: Complete walkthrough from installation to your first API call in under 10 minutes. Learn how to authenticate requests using API keys or JWT tokens. Understand rate limits and best practices for high-volume usage. ### API documentation components #### Parameter fields Example of parameter documentation: Unique identifier for the user. Must be a valid UUID v4 format. User's email address. Must be valid and unique within the system. Maximum number of results to return. Range: 1-100. Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` #### Response fields Example of response field documentation: Unique identifier assigned to the newly created user. ISO 8601 formatted timestamp of when the user was created. List of permission strings assigned to this user. #### Expandable nested fields Example of nested field documentation: Complete user object with all associated data. User profile information including personal details. User's first name as entered during registration. URL to user's profile picture. Returns null if no avatar is set. ### Media and advanced components #### Frames for images Wrap all images in frames: Main dashboard showing analytics overview

Main dashboard showing analytics overview

#### Videos Use the HTML video element for self-hosted video content:

Embed YouTube videos using iframe elements: #### Tooltips Example of tooltip usage: API #### Updates Use updates for changelogs: ## New features - Added bulk user import feature - Improved error messages with actionable suggestions ## Bug fixes - Fixed pagination issue with large datasets - Resolved authentication timeout problems ## Required page structure Every documentation page must begin with YAML frontmatter: ```yaml --- title: "Clear, specific, keyword-rich title" description: "Concise description explaining page purpose and value" --- ``` ## Content quality standards ### Code examples requirements - Always include complete, runnable examples that users can copy and execute - Show proper error handling and edge case management - Use realistic data instead of placeholder values - Include expected outputs and results for verification - Test all code examples thoroughly before publishing - Specify language and include filename when relevant - Add explanatory comments for complex logic - Never include real API keys or secrets in code examples ### API documentation requirements - Document all parameters including optional ones with clear descriptions - Show both success and error response examples with realistic data - Include rate limiting information with specific limits - Provide authentication examples showing proper format - Explain all HTTP status codes and error handling - Cover complete request/response cycles ### Accessibility requirements - Include descriptive alt text for all images and diagrams - Use specific, actionable link text instead of "click here" - Ensure proper heading hierarchy starting with H2 - Provide keyboard navigation considerations - Use sufficient color contrast in examples and visuals - Structure content for easy scanning with headers and lists ## Component selection logic - Use **Steps** for procedures and sequential instructions - Use **Tabs** for platform-specific content or alternative approaches - Use **CodeGroup** when showing the same concept in multiple programming languages - Use **Accordions** for progressive disclosure of information - Use **RequestExample/ResponseExample** specifically for API endpoint documentation - Use **ParamField** for API parameters, **ResponseField** for API responses - Use **Expandable** for nested object properties or hierarchical information ```` ## Enhance with MCP server Connect the Mintlify MCP server to Cursor to give it access to search the Mintlify documentation while helping you write. When you connect the MCP server, Cursor searches the up to date Mintlify documentation for context so you don't have to leave your IDE to reference documentation. See [Model Context Protocol](/ai/model-context-protocol#example%3A-connect-to-the-mintlify-mcp-server) for complete setup instructions. # Create developer documentation Source: https://mintlify-docs.mintlify.app/guides/developer-documentation Build documentation that helps developers integrate with your APIs, SDKs, and tools. Developer documentation helps people understand and integrate with your product. Good documentation helps people do more with your product, reduces support burden, speeds up adoption, and improves developer experience. Mintlify provides infrastructure built for developer documentation. * **API reference generation**: Generate interactive [API references](/api-playground/overview) from OpenAPI specifications that let developers test endpoints in your documentation. * **Code blocks with explanations**: The [assistant](/ai/assistant) explains code examples in context, helping developers understand implementation details. * **Git sync**: Keep documentation in sync with your codebase using [GitHub](/deploy/github) or [GitLab](/deploy/gitlab). * **Versioning**: Maintain documentation for multiple [versions](/organize/navigation#versions) so developers on older versions can still find accurate information. ## Prerequisites If you haven't created a Mintlify project yet, see the [Quickstart](/quickstart) to deploy your site. * Your API specification in OpenAPI format (if documenting an API) * A Git repository for your documentation * Admin access to your Mintlify organization ## Migrate existing documentation If you're creating documentation from scratch, skip to [Plan your documentation structure](#plan-your-documentation-structure). ### Audit existing content Review your current documentation to understand what you have and what you need to migrate. * **API reference**: Is it generated from a spec or hand-written? What endpoints do you document? * **Guides and tutorials**: What integration guides exist? Are they current? * **Code examples**: What languages and frameworks do you use? * **SDK documentation**: Do you have separate documentation for each SDK? * **Changelog**: Do you maintain a changelog or release notes? * **Metadata**: Do you have metadata for your content like dates, authors, and tags? ### Export your existing content * Export to **Markdown** for the simplest migration to Mintlify. * Export **OpenAPI specs** for API reference content. * Export to **HTML** if Markdown isn't available, then convert to Markdown. ## Plan your documentation structure Developer documentation typically includes several content types. Structure your navigation around how your users understand your product. ```json docs.json example theme={null} { "navigation": { "groups": [ { "group": "Get Started", "pages": [ "introduction", "quickstart", "authentication" ] }, { "group": "Guides", "pages": [ "guides/webhooks", "guides/error-handling", "guides/rate-limits", "guides/pagination" ] }, { "group": "API Reference", "pages": [ "api-reference/overview", "api-reference/users", "api-reference/orders", "api-reference/products" ] }, { "group": "SDKs", "pages": [ "sdks/javascript", "sdks/python", "sdks/go" ] } ] } } ``` See [Navigation](/organize/navigation) for more configuration options. ## Set up your API reference If you have an API, generate an interactive reference from your OpenAPI specification. Add your OpenAPI specification file to your project. You can use YAML or JSON format. ```text theme={null} your-project/ ├── docs.json ├── openapi.yaml └── api-reference/ └── overview.mdx ``` Reference your OpenAPI file in your `docs.json` configuration. ```json Configuration example theme={null} { "openapi": "openapi.yaml" } ``` Add the endpoints to your `docs.json` navigation. See [OpenAPI setup](/api-playground/openapi-setup) for configuration options. ```json Navigation example theme={null} { "group": "API Reference", "pages": [ "api-reference/overview", "api-reference/users/list-users", "api-reference/users/get-user", "api-reference/users/create-user" ] } ``` ## Set up the assistant The assistant helps developers find answers and understand code examples. Configure it from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings). * **Sample questions**: Add developer-focused questions like "How do I authenticate API requests?" or "Show me how to handle webhooks." * **Code explanations**: The assistant can explain code blocks in context when developers ask questions about specific examples. ## Set up versioning If you maintain multiple API versions, configure versioning so developers find documentation for their version. ```json Versioning example theme={null} { "versions": ["v2", "v1"], "navigation": { "groups": [ { "group": "API Reference", "version": "v2", "pages": ["v2/api-reference/users"] }, { "group": "API Reference", "version": "v1", "pages": ["v1/api-reference/users"] } ] } } ``` See [Versions](/organize/navigation#versions) for more information. ## Connect to your repository Install the Mintlify [GitHub App](/deploy/github) to keep documentation in sync with your codebase and enable contributions. Link your GitHub repository in the [dashboard](https://dashboard.mintlify.com). This enables automatic deployments when you push changes. Set your production branch and enable preview deployments for pull requests. This lets you review documentation changes before they go live. If you use GitLab, see [GitLab](/deploy/gitlab) for configuration instructions. ## Maintain your documentation Developer documentation needs regular updates so that information is accurate and usable. Update your OpenAPI specification whenever you release changes. If your specification is generated from code, automate this in your release process. Review code examples when you release new SDK versions or product updates. Outdated examples cause integration failures and support requests. Document breaking changes, new features, and deprecations. Developers rely on changelogs to understand what changed between versions. See [Changelogs](/create/changelogs) for more information. Review assistant conversations and search analytics to identify gaps in your documentation. If developers repeatedly ask about the same topic, improve that section. See [Maintenance](/guides/maintenance) for more information. ## Next steps Your developer documentation is ready to launch. After deploying: 1. Announce the documentation to your developer community. 2. Monitor search patterns and assistant conversations for gaps. 3. Set up a process to update docs with each API release. 4. Gather feedback from developers to improve content over time. # Guides Source: https://mintlify-docs.mintlify.app/guides/index Learn how to create effective documentation with best practices and workflows. The guides in this section contain advice for creating documentation that helps your users succeed. Whether you're starting from scratch or improving existing docs, these guides help you plan, write, and maintain your documentation. Above all else, consider your users' needs and goals. Document what helps them use your product and get back to their tasks. ## Topics ### AI tools Use AI-powered tools to accelerate your documentation workflow. * [Automate documentation updates](/guides/automate-agent): Tutorial that teaches how to set up automated documentation updates using the agent. * [Build an in-app assistant](/guides/assistant-embed): Tutorial that teaches how to add an AI chat bot in a React app to help users find answers from your documentation. * [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf): Guides for using AI coding assistants to maintain documentation. * [GEO](/guides/geo): Best practices for optimizing your documentation for AI search and answer engines. ### API documentation Create API documentation that lets users test and learn how to use your API, and is easy to maintain. * [Migrate from MDX to OAS](/guides/migrating-from-mdx): Move your API documentation from individual MDX pages to autogenerated pages from an OpenAPI specification. ### Best practices Make your documentation best in class. * [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible. * [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. * [Content templates](/guides/content-templates): Copy and modify templates for each content type. * [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation. * [Internationalization](/guides/internationalization): Set up multi-language documentation to reach global audiences. * [Linking](/guides/linking): Create internal links, reference API endpoints, and maintain link integrity across your documentation. * [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date. * [Media](/guides/media): Add images, videos, and other media effectively while managing maintenance burden. * [Organize navigation](/guides/navigation): Design information architecture that works for your users. * [SEO](/guides/seo): Optimize your docs for search engines. * [Style and tone](/guides/style-and-tone): Write with a consistent voice. * [Understand your audience](/guides/understand-your-audience): Research and serve your users' needs and goals. ### Git workflows Understand Git to get the most out of Mintlify and a docs-as-code approach to documentation. * [Git concepts](/guides/git-concepts): Learn the fundamentals of Git for documentation. * [Branches](/guides/branches): Use branches to manage documentation changes. ### Use cases Learn how Mintlify supports different use cases and find a solution that works for you. * [Create developer documentation](/guides/developer-documentation): Help your users get the most from your product or API with developer documentation that answers questions and gets people back to their main tasks. * [Create a knowledge base](/guides/knowledge-base): Set up an internal knowledge base to consolidate information for your team, improve search, and reduce maintenance burden. * [Create a support center](/guides/support-center): Build a self-service support center that helps customers find answers, reduces ticket volume, and improves customer satisfaction. * [Create a custom frontend](/guides/custom-frontend): Use the Mintlify Astro integration to render your documentation with a fully custom frontend. ## Where to start Learn about content types to understand how to structure your docs. Learn how to use metrics and feedback to make your docs better. Automate documentation updates with the agent. Learn Git workflows for collaborative documentation. # Create a knowledge base Source: https://mintlify-docs.mintlify.app/guides/knowledge-base Host your internal knowledge base on Mintlify to consolidate information for your team, improve search, and reduce maintenance burden. An internal knowledge base helps your team find answers and maintain a source of truth. If your team has information spread across different channels and platforms, people might find inaccurate or no information when they search for answers. A centralized knowledge base solves this by putting answers where everyone can find them and giving your team a specific place to record shared knowledge. Mintlify provides the infrastructure for knowledge bases that your entire team can contribute to. * **AI-powered search**: The [assistant](/ai/assistant) answers questions using your knowledge base content, so people find answers without knowing exactly where to look. * **Slack integrations**: Add the assistant to [Slack](/ai/slack-bot) so your team can ask questions and use the [agent](/agent/slack) to capture knowledge from conversations. * **Low-barrier contributions**: The [web editor](/editor) and [agent](/agent/index) let anyone on your team update content without learning Git or Markdown. * **Authentication built-in**: Control access with [SSO or OAuth](/deploy/authentication-setup), and use [groups](/deploy/authentication-setup#control-access-with-groups) to show different content to different teams. ## Prerequisites If you haven't created a Mintlify project yet, see the [Quickstart](/quickstart) to deploy your site. * An authentication system (SSO or OAuth provider like Okta or Azure AD) * Control over your domain for hosting * Admin access to your Mintlify organization ## Migrate existing content If you're creating a knowledge base from scratch, skip to [Design the navigation structure](#design-the-navigation-structure). ### Audit existing content Catalog the content you currently have in your existing knowledge base. This helps you understand what content you need to migrate, plan how to organize it in your new knowledge base, identify any gaps in your content, and confirm that you moved all of your content to your new knowledge base. * **Total number of articles**: Helps estimate migration effort and track completeness. * **Topics and content**: Informs your navigation structure and content organization. * **Current organization**: See how your content is currently organized and whether it matches your desired structure. * **Content types**: Determine any content conversion requirements for text, PDFs, videos, and embedded content. * **Metadata**: Identify any metadata to preserve like dates, authors, and tags. * **Access requirements**: Determine the best authentication approach for your knowledge base. ### Export your existing content Most knowledge base platforms support exporting content in standard formats. The format you choose depends on your current platform and your priorities. * Export to **Markdown** for the simplest migration to Mintlify. (recommended) * Export to **HTML** if Markdown isn't available. You must convert your content to Markdown later. * Export to **JSON or CSV** if you have structured metadata to preserve. ## Design the navigation structure Your navigation structure determines how people find content in your knowledge base. You can recreate your existing structure or redesign it to better match how your team thinks about the content. Migrating is a good time to improve your structure. Consider whether your current organization actually works for your team, or if you can reorganize to make information easier to find. Your `docs.json` file defines the navigation structure of your knowledge base. Create this file at the root of your project repository. ```json theme={null} { "navigation": { "groups": [ { "group": "Finance", "pages": [ "finance/overview", "finance/budgeting-process", "finance/expense-reports", "finance/cost-allocation" ] }, { "group": "HR", "pages": [ "hr/overview", "hr/onboarding", "hr/benefits", "hr/time-off-policy" ] }, { "group": "Engineering", "pages": [ "engineering/overview", "engineering/dev-setup", "engineering/deployment", "engineering/code-standards" ] } ] } } ``` See [Navigation](/organize/navigation) for more information on how to structure your knowledge base. ## Set up authentication Determine who needs access to what content in your knowledge base. If everyone should have access to the entire knowledge base, set up only [authentication](/deploy/authentication-setup). If you need to restrict access to certain content to specific users or groups, set up authentication with [group-based access control](/deploy/authentication-setup#control-access-with-groups). ## Migrate your content Move your exported content into a folder structure that matches the navigation structure you designed. Convert content to Markdown if needed, add any missing frontmatter, and set up internal links. Create folders that match your `docs.json` structure. For example, if your `docs.json` has a Finance group, create a `finance/` folder: ```text theme={null} your-project/ ├── docs.json ├── finance/ │ ├── overview.mdx │ ├── budgeting-process.mdx │ ├── expense-reports.mdx │ └── cost-allocation.mdx ├── hr/ │ ├── overview.mdx │ ├── onboarding.mdx │ ├── benefits.mdx │ └── time-off-policy.mdx └── engineering/ ├── overview.mdx ├── dev-setup.mdx ├── deployment.mdx └── code-standards.mdx ``` Place each article in its corresponding folder. The file path must match the path in your `docs.json`. For example, if `docs.json` references `"finance/expense-reports"`, the file should be `finance/expense-reports.mdx` in your project repository. Every `.mdx` file needs frontmatter at the top with metadata. Every page requires a title and description. See [Pages](/organize/pages) for more information on page metadata. ```mdx theme={null} --- title: "Expense Report Process" description: "How to submit and track expense reports" --- Your content here... ``` Link between pages using paths from your project root. ```mdx theme={null} See [Onboarding Guide](/hr/onboarding) for new employee setup. For questions, contact [HR Benefits Team](/hr/benefits#common-questions). ``` If you exported your content as HTML, convert it to Markdown. Some tools that can help include: * **Pandoc**: Command-line tool that converts between many formats. * **CloudConvert**: Online converter supporting HTML, DOCX, PDF, and more. * **VS Code extensions**: Search for "HTML to Markdown" in extensions. If you have PDFs, videos, or other media, decide how to include them in your knowledge base. * **Embed videos**: Embed videos or link to hosted videos. * **Link to PDFs**: Add PDFs to your project repository and link to them from relevant pages. * **Convert PDFs to Markdown**: If you want the content of a PDF to be a page, convert PDFs to Markdown. ## Set up the assistant The assistant is automatically enabled for Pro and Enterprise plans. The assistant lets your team ask questions and get answers with cited sources from your knowledge base. Configure the assistant from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings): * **Sample questions**: Add common questions like "how do I submit an expense report" or "what is the vacation policy" so people can get answers with one click. * **Search sites**: Include additional sites the assistant can search when answering questions. * **Deflection email**: Set a support email for questions the assistant can't answer. ### Add the assistant to Slack The [Slack bot](/ai/slack-bot) lets your team ask the assistant questions without leaving Slack. Create a channel where the bot responds to every message or let people @mention the bot in any channel. ## Enable team contributions A knowledge base stays accurate when everyone can update it, not just the people who set it up. Mintlify provides three ways for team members to contribute quickly to your knowledge base. ### Web editor The [web editor](/editor) lets anyone create and edit pages in their browser. Contributors can: * Edit pages visually or in Markdown. * Drag and drop to reorganize navigation. * Upload images and media. * Create branches and pull requests for review. This works well for subject matter experts who know the content but aren't comfortable with code workflows. ### Agent The [agent](/agent/index) in your dashboard creates documentation updates from natural language prompts. Describe what you want to change, and the agent creates a pull request with the updates. For example, a team member could prompt "add a section to the expense policy page explaining how to submit receipts for meals over \$50" and copy the existing expense policy page into the prompt. The agent would draft the content and open a PR for review. ### Capture knowledge from Slack Teams share valuable information in Slack that often never makes it into documentation. The [agent in Slack](/agent/slack) can capture this knowledge and convert it into structured documentation. When someone shares useful information in a Slack thread, any team member can mention `@mintlify` with instructions to document it. The agent reads the conversation, extracts the relevant information, and creates a pull request. This is useful for capturing technical decisions, troubleshooting solutions, and process explanations while the context is still fresh. For example, if your team discussed how to configure a new integration in a thread, you could reply: > @mintlify Create a guide for configuring the Acme integration based on this conversation. The agent uses the thread context to create documentation that captures the key information from the discussion. ### Locally Anyone with access to your knowledge base repository can work locally in their preferred editor and push changes to your repository. ## Establish maintenance workflows A knowledge base can decay quickly without maintenance. Set up systems to keep content up to date and help your team contribute to the knowledge base. Designate an owner or small team for each section. They don't have to write all the content, but they're responsible for: * Reviewing content regularly. * Flagging outdated information. * Approving new pages in their section. * Responding when people report errors. Content becomes stale over time. Establish a review schedule. * **Critical content**: Review every 30 days * **Standard content**: Review every 90 days * **Evergreen content**: Review yearly When reviewing, check: * Are links still valid? * Have systems or processes changed? * Are examples current? * Is there new information that should be added? Make it easy for anyone to improve the knowledge base. Your guidelines should cover: * **Format**: Do you have specific templates or format requirements? * **Process**: How should someone propose and submit changes? * **Review**: Who reviews submissions? What's the turnaround time? * **Scope**: What types of content are in scope? Review how your team uses the knowledge base to prioritize content and identify areas for improvement. Set a regular cadence for reviewing usage metrics—monthly or quarterly are good intervals. * Which articles get the most views? Invest in keeping these accurate and easy to read. * Which articles get no views? Consider removing them or improving discoverability. * What's the bounce rate? If people leave immediately, the content might not be helpful or navigation could be improved. ## Next steps Your knowledge base is ready to launch. After deploying: 1. Announce the knowledge base to your team. 2. Monitor usage and search patterns in your analytics. 3. Encourage contributions when people find gaps. 4. Review and update content regularly. The most successful knowledge bases evolve based on how teams actually use them. # Organize navigation Source: https://mintlify-docs.mintlify.app/guides/navigation Design information architecture that aligns with user needs. This page explains why and how to organize your documentation in a way that makes sense for your users. ## Why is navigation important? Navigation might seem unimportant because experienced users looking for specific answers typically navigate directly to pages via a search engine or your documentation site's search bar. But the information architecture of your documentation helps people build a mental model for how to think about your product, and provides structure for people and AI tools that use your documentation. Well designed navigation helps people quickly grasp your product and succeed when using your documentation. ## Map the foundation with stakeholders Align with key stakeholders like your founders, product managers, or engineering leads on how your product works, what's most important, and how users should interact with it. Example questions to ask: * What's the simplest way to explain how the product works? * What are the product's core building blocks? * How do users typically adopt the product? Where do people most often get stuck? * How does the product's architecture influence how people use it? * What are the most important integrations or dependencies? * What is changing or evolving in the product? * If the product was broken into different layers, what would they be? Would it be by tasks that people perform or by features that people use? ## Validate your assumptions Once you've established a structure, you need to validate whether it actually works for real users. The way people navigate your documentation often reveals gaps in your information architecture that internal teams might overlook. ### Track real user journeys Use tools like session replays (for example, [FullStory](https://www.fullstory.com), [Hotjar](https://www.hotjar.com)) or analytics (for example, [Mixpanel](https://mixpanel.com)) to study how users move through your docs. Pay attention to: * **Entry points:** Where do users start their journey? Are they coming from search, a support ticket, or directly from your product? * **Navigation patterns:** Do they follow the expected navigation structure, or do they take unexpected detours? * **Friction points:** Where do users pause, loop back, or abandon their session? These could indicate unclear organization or missing content. * **Search behavior:** Are users searching for terms that don't exist in your documentation? This might highlight gaps in your content or misalignment in terminology. ### Test with real users Analytics help surface trends, but direct conversations provide deeper insights. Get on research calls where customers attempt to find answers to specific questions. Ask them to narrate their thought process as they navigate. New hires are also a great proxy for users since they don't have as much prior context as tenured members of your team. Before they get too familiar with your product from the inside, ask them to complete a task using only the documentation. Have them outline in detail how they approached the task. Where they clicked first, how they interpreted section names, and where they got stuck. Their instincts can reveal whether your docs are intuitive or if they assume too much knowledge. ## Identify common challenges Based on your observations, look for these common navigation problems: * **Overloaded categories:** Too many top-level sections can overwhelm users. Consider grouping related topics together. * **Hidden essential content:** Don't bury critical information. Prioritize frequently accessed content. * **Unclear section names:** If users hesitate before clicking, your labels might not be intuitive. Align terminology with how your audience naturally thinks. Try to design an elegant and functional information architecture, but remember, it's hard to make documentation that works for absolutely everyone. Consider the majority of your users and what helps them succeed. ## Iterate over time Above all, stay flexible. Your navigation should evolve with your product and user needs. You don't have to be right on the first try. # SEO Source: https://mintlify-docs.mintlify.app/guides/seo Improve SEO to increase documentation discoverability. This page explains fundamental strategies to optimize your documentation SEO. ## Content basics Make your writing and structure easy for search engines to scan. * **Headings and subheadings:** Use sequential, meaningful headers to structure your content. Each page has an H1 created from the `title:` property in the frontmatter. * **Short paragraphs and bullet points:** Break down large chunks of text into easily readable sections. Use bullet points and numbered lists where appropriate. * **Internal linking:** Link to related content using descriptive anchor text. For example, "Learn more about rate limiting" instead of "Click here." ## Technical SEO basics Once your content is optimized, ensure your documentation performs well from a technical standpoint. These basic technical SEO practices help make your docs more discoverable: * **Meta tags and descriptions:** Craft SEO-friendly titles (50-60 characters) and descriptions (150-160 characters) for each page. Most [meta tags](/optimize/seo) are automatically generated. * **Alt text for images:** Provide descriptive alt text for images with relevant keywords. For example, "OAuth 2.0 API authentication flow" instead of just "diagram". This enhances SEO and accessibility. * **Sitemaps:** Ensure your sitemap is up-to-date. Mintlify automatically generates a sitemap. However, you can manually create a sitemap if you prefer a custom format. Once created, search engines index site maps over time, but you can submit your sitemap directly to Google Search Console to speed up the process. ## Page performance Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) to identify areas for technical SEO improvement. Examples of more advanced optimizations: * **Optimize media for speed:** Compress images using formats like WebP or AVIF and ensure your pages load quickly (ideally under 3 seconds). * **Structured data (schema markup):** Add schema markup (like HowTo, FAQ) to your pages to help search engines better understand and rank your content. ## Keyword research To increase organic traffic, invest time into understanding which keywords help users land on your documentation. * **Keyword research:** Use free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases or long-tail keywords. * **Integrate keywords naturally:** Add keywords naturally into headings, subheadings, and throughout the body text. Don't overstuff keywords. Your documentation should be written for your users, not search engines. # Style and tone Source: https://mintlify-docs.mintlify.app/guides/style-and-tone Write effective technical documentation with consistent style. This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation. ## Writing principles * **Be concise.** People are reading documentation to achieve a goal. Get to the point quickly. * **Clarity over cleverness.** Be simple, direct, and avoid jargon or complex sentence structure. * **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file." * **Be skimmable.** Use headlines to orient readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan. * **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal. ## Common writing mistakes * **Spelling and grammar mistakes.** Even a few spelling and grammar mistakes in your documentation make it less credible and harder to read. * **Inconsistent terminology.** Calling something an "API key" in one paragraph then "API token" in the next makes it difficult for users to follow along. * **Product-centric terminology.** Your users don't have the full context of your product. Use language that your users are familiar with. * **Colloquialisms.** Especially for localization, colloquialisms hurt clarity. ## Tips for enforcing style Leverage existing style guides to standardize your documentation: * [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) * [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse) * [Google Developer Documentation Style Guide](https://developers.google.com/style) When you know which writing principles you want to implement, automate as much as you can. You can use [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh). ## Related pages Choose the right content type for your documentation goals. Make your documentation accessible to more users. Learn text formatting and styling options. Improve documentation discoverability. # Create a support center Source: https://mintlify-docs.mintlify.app/guides/support-center Build a self-service support center that helps customers find answers, reduces ticket volume, and improves customer satisfaction. A support center helps customers solve problems and find information about your product. When customers can find answers themselves, they get help faster and your support team can focus on complex issues that require their expertise. Mintlify provides infrastructure for support centers that scale with your customer base. * **AI-powered search**: The [assistant](/ai/assistant) answers customer questions using your support content, so people can find answers without knowing exactly where to look or specific terms to search for. * **Feedback collection**: Built-in [feedback widgets](/optimize/feedback) let customers rate articles and report issues so you can improve content. * **Analytics**: Track which articles get views, what questions customers ask, and where they struggle. * **Authentication**: Use [SSO or OAuth](/deploy/authentication-setup) to show personalized content based on customer plans or account types. ## Prerequisites If you haven't created a Mintlify project yet, see the [Quickstart](/quickstart) to deploy your site. * Content for your most common support topics * Admin access to your Mintlify organization * Domain for hosting your support center ## Migrate existing content If you're creating a support center from scratch, skip to [Plan your support center structure](#plan-your-support-center-structure). ### Audit existing content Review your current support resources to understand what to migrate. * **Help articles**: What topics do you address? Which articles get the most views? * **FAQs**: Do you have frequently asked questions that should become articles? * **Support tickets**: What questions do customers ask repeatedly? These should become self-service content. * **Product documentation**: Is there overlap between support content and product docs? ### Export your existing content * Export to **Markdown** for the simplest migration to Mintlify. * Export to **HTML** if Markdown isn't available, then convert to Markdown. * Export **ticket data** to identify common questions that need documentation. ## Plan your support center structure Organize your support center around customer problems, not product features. Customers arrive with questions and goals, so structure content that aligns with how they think about your product and common tasks. Review your support tickets to understand what customers actually ask about. This helps you prioritize content and structure navigation around real problems. ```json theme={null} { "navigation": { "groups": [ { "group": "Get Started", "pages": [ "getting-started/quick-setup", "getting-started/first-steps" ] }, { "group": "Account", "pages": [ "account/billing", "account/plans", "account/team-management", "account/security" ] }, { "group": "Using the Product", "pages": [ "product/feature-one", "product/feature-two", "product/integrations" ] }, { "group": "Troubleshooting", "pages": [ "troubleshooting/common-errors", "troubleshooting/connectivity", "troubleshooting/performance" ] } ] } } ``` See [Navigation](/organize/navigation) for more configuration options. ## Write effective support content Support content should help customers solve problems quickly. Every article should answer one specific question or solve one specific problem. Organize related content into groups instead of creating overly long pages that have too much information. ### Structure articles for scanning Customers scan support pages looking for their specific issue. Use clear headings and short paragraphs. ```mdx Example support page theme={null} --- title: "Fix login issues" description: "Troubleshoot common problems signing in to your account" --- ## Reset your password If you forgot your password, request a reset link from the login page. 1. Go to the login page. 2. Select **Forgot password**. 3. Enter your email address. 4. Check your inbox for the reset link. ## Clear browser cache Old cached data can cause login problems. Clear your browser cache and try again. ## Check account status If your account is suspended or deactivated, you'll see an error when logging in. Contact support if you believe this is a mistake. ``` ### Include step-by-step instructions When explaining how to do something, use numbered steps. Click the gear icon in the toolbar. Click **Billing** in the navigation menu. Click **Update** next to your current payment method and enter new details. ### Add visual aids Screenshots and diagrams help customers confirm they're in the right place. ```mdx Example screenshot theme={null} ![Settings page with billing section highlighted](/images/billing-settings.png) ``` ## Set up the assistant The assistant answers customer questions using your support content. Configure it from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings). Add common questions customers ask, such as: * "How do I cancel my subscription?" * "Why was my payment declined?" * "How do I add team members?" Sample questions appear as quick-access buttons, helping customers get answers with one click. Configure a support email for questions the assistant can't answer. This ensures customers can still reach your team when self-service isn't enough. Check assistant conversations regularly to identify: * Questions the assistant can't answer (content gaps) * Incorrect or incomplete answers (content to improve) * Common question patterns (content to prioritize) ## Enable feedback collection Feedback helps you understand which pages are helpful and which need improvement. Review [feedback](/optimize/feedback) to see which pages customers find helpful and which need improvement. Read all comments and update pages based on valid feedback. ## Set up analytics Monitor how customers use your support center to improve content over time. * **Popular articles**: Which articles get the most views? Keep these accurate and well-maintained. * **Search queries**: What do customers search for? Create content for common searches that return no results. * **Assistant conversations**: What questions does the assistant receive? Use this to identify content gaps. ## Restrict content by customer segment If you have different customer tiers or product plans, show relevant content to each segment using group-based access control. Configure [authentication](/deploy/authentication-setup) to identify customers when they visit your support center. Return group information in your user data to define customer segments based on plan type, account status, or other attributes. See [User data format](/deploy/authentication-setup#user-data-format) for details. Use frontmatter to specify which groups can see each article. ```mdx theme={null} --- title: "Enterprise SSO setup" groups: ["enterprise"] --- ``` ## Maintain your support center Support content becomes outdated as your product changes. Establish processes to keep content accurate. When you ship product changes, update affected support articles. Include documentation updates in your release process. Check article ratings and customer feedback weekly. Address negative feedback promptly. It often indicates confusing or incorrect content. If customers submit tickets for issues covered in your support center, investigate why self-service didn't work. The article might be hard to find, unclear, or incomplete. Remove or archive articles about deprecated features. Outdated content confuses customers and reduces trust in your support center. ## Next steps Your support center is ready to launch. After deploying: 1. Link to your support center from your product and website. 2. Monitor assistant conversations and search queries to find content gaps. 3. Review feedback ratings weekly and improve low-rated articles. 4. Track ticket volume to measure self-service effectiveness. A good support center reduces support costs while improving customer satisfaction. Invest in content that answers common questions effectively. # Windsurf Source: https://mintlify-docs.mintlify.app/guides/windsurf Configure Windsurf to be your writing assistant. Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories. ## Use Windsurf with Mintlify Windsurf's Cascade AI assistant can be tuned to write documentation according to your standards using Mintlify components. Workspace rules and memories provide persistent context about your project, ensuring more consistent suggestions from Cascade. * **Workspace rules** are stored in your documentation repository and shared with your team. * **Memories** provide individual context that builds up over time. We recommend setting up workspace rules for shared documentation standards. You can develop memories as you work, but since they are not shared, they are not consistent across team members. Create workspace rules in the `.windsurf/rules` directory of your docs repo. See [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) in the Windsurf documentation for more information. ## Example workspace rule This rule provides Cascade with context about Mintlify components and general technical writing best practices. You can use this example rule as-is or customize it for your documentation: * **Writing standards**: Update language guidelines to match your style guide. * **Component patterns**: Add project-specific components or modify existing examples. * **Code examples**: Replace generic examples with real API calls and responses for your product. * **Style and tone preferences**: Adjust terminology, formatting, and other rules. Save your rule as a `.md` file in the `.windsurf/rules` directory of your docs repo. ````mdx theme={null} # Mintlify technical writing rule ## Project context - This is a documentation project on the Mintlify platform - We use MDX files with YAML frontmatter - Navigation is configured in `docs.json` - We follow technical writing best practices ## Writing standards - Use second person ("you") for instructions - Write in active voice and present tense - Start procedures with prerequisites - Include expected outcomes for major steps - Use descriptive, keyword-rich headings - Keep sentences concise but informative ## Required page structure Every page must start with frontmatter: ```yaml --- title: "Clear, specific title" description: "Concise description for SEO and navigation" --- ``` ## Mintlify components ### docs.json - Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation ### Callouts - `` for helpful supplementary information - `` for important cautions and breaking changes - `` for best practices and expert advice - `` for neutral contextual information - `` for success confirmations ### Code examples - When appropriate, include complete, runnable examples - Use `` for multiple language examples - Specify language tags on all code blocks - Include realistic data, not placeholders - Use `` and `` for API docs ### Procedures - Use `` component for sequential instructions - Include verification steps with `` components when relevant - Break complex procedures into smaller steps ### Content organization - Use `` for platform-specific content - Use `` for progressive disclosure - Use `` and `` for highlighting content - Wrap images in `` components with descriptive alt text ## API documentation requirements - Document all parameters with `` - Show response structure with `` - Include both success and error examples - Use `` for nested object properties - Always include authentication examples ## Quality standards - Test all code examples before publishing - Use relative paths for internal links - Include alt text for all images - Ensure proper heading hierarchy (start with h2) - Check existing patterns for consistency ```` ## Working with Cascade Once your rules are set up, you can use Cascade to assist with various documentation tasks. See [Cascade](https://docs.windsurf.com/windsurf/cascade) in the Windsurf documentation for more information. ### Example prompts **Writing new content**: ```text wrap theme={null} Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL. ``` **Improving existing content**: ```text wrap theme={null} Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow. ``` **Creating code examples**: ```text wrap theme={null} Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses. ``` **Maintaining consistency**: ```text wrap theme={null} Check if this new page follows our documentation standards and suggest any needed changes. ``` ## Enhance with MCP server Connect the Mintlify MCP server to Windsurf to give Cascade access to search the Mintlify documentation while helping you write. When you connect the MCP server, Cascade searches the up to date Mintlify documentation for context so you don't have to leave your IDE to reference documentation. See [Model Context Protocol](/ai/model-context-protocol#example%3A-connect-to-the-mintlify-mcp-server) for complete setup instructions. # Install the CLI Source: https://mintlify-docs.mintlify.app/installation Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site. Decorative graphic representing the CLI.

Decorative graphic representing the CLI.

Use the [CLI](https://www.npmjs.com/package/mint) to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and features, and catch issues like broken links or accessibility problems. The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats. ## Prerequisites * [Node.js](https://nodejs.org/en) v20.17.0+ (LTS versions recommended) installed * [Git](https://git-scm.com/downloads) installed * Your documentation repository cloned locally ### Clone your repository 1. Go to the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard. 2. Note your repository location. It is one of these formats: * `mintlify-community/docs-{org-name}-{id}` (Mintlify-hosted repository) * `your-org/your-repo` (your own GitHub repository) Replace `your-org/your-repo` with your actual repository details from [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings). ```bash theme={null} git clone https://github.com/your-org/your-repo cd your-repo ``` **GitHub App required.** To enable automatic deployments when you push changes, you must install the GitHub app. See [GitHub](/deploy/github) for more information. You can clone your repository as a private or public repository. Public repositories are visible to anyone who navigates to the repository URL. Private repositories are only visible to people in your organization. On the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard, select **Clone as private** or **Clone as public**. ## Install the CLI Run the following command to install the CLI: ```bash npm theme={null} npm i -g mint ``` ```bash pnpm theme={null} pnpm add -g mint ``` ## Preview locally Navigate to your documentation directory containing your `docs.json` file and run: ```bash theme={null} mint dev ``` A local preview of your documentation is available at `http://localhost:3000`. Alternatively, if you do not want to install the CLI globally, you can run a one-time script: ```bash theme={null} npx mint dev ``` ### Custom ports By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command: ```bash theme={null} mint dev --port 3333 ``` If you attempt to run on a port that is already in use, the CLI uses the next available port: ```mdx theme={null} Port 3000 is already in use. Trying 3001 instead. ``` ## Skip OpenAPI processing If you have many OpenAPI files, skip OpenAPI file processing during local development to improve performance by using the `--disable-openapi` flag: ```bash theme={null} mint dev --disable-openapi ``` ### Preview as a specific group If you use group-based access control to restrict access to your documentation, you can preview as a specific authentication group by using the `--groups [groupname]` flag. For example, if you have a group named `admin`, you can preview as a member of that group with the command: ```bash theme={null} mint dev --groups admin ``` ## Create a new project To create a new documentation project, run the following command: ```bash theme={null} mint new [directory] ``` This command clones the [starter kit](https://github.com/mintlify/starter) into a specified directory. If you do not specify a directory, the CLI tool prompts you to create a new subdirectory or overwrite the current directory. Overwriting the current directory deletes any existing files. The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project. ### Flags | Flag | Description | Required | | --------- | -------------------------------------------------------------------------------------- | -------- | | `--name` | Set the name of the new project. | Yes | | `--theme` | Set the [theme](/customize/themes) of the new project. | Yes | | `--force` | Overwrite the current directory without prompting, even if it contains existing files. | No | When running `mint new` in non-interactive environments like CI/CD pipelines or with AI coding agents, you must provide all required flags (`--name` and `--theme`). The CLI automatically detects non-interactive environments. If required flags are missing, it outputs usage instructions instead of hanging on prompts. ## Update the CLI If your local preview is out of sync with what you see on the web in the production version, update your local CLI: ```bash theme={null} mint update ``` If this `mint update` command is not available on your local version, re-install the CLI with the latest version: ```bash npm theme={null} npm i -g mint@latest ``` ```bash pnpm theme={null} pnpm add -g mint@latest ``` ## Additional commands ### Find broken links Identify any broken internal links with the following command: ```bash theme={null} mint broken-links ``` The command ignores files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files are reported as broken. To also check anchor links like `/path/to/page#anchor`, use the `--check-anchors` flag: ```bash theme={null} mint broken-links --check-anchors ``` ### Find accessibility issues Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command: ```bash theme={null} mint a11y ``` Use flags to check for specific accessibility issues. ```bash theme={null} # Check only for missing alt text mint a11y --skip-contrast # Check only for color contrast issues mint a11y --skip-alt-text ``` ### Validate documentation build Validate your documentation build in strict mode, which exits with an error if there are any warnings or errors. Use this command for CI/CD pipelines to prevent broken documentation deployments. ```bash theme={null} mint validate ``` Use flags to configure the validation command. * `--groups [groupname]`: Mock user groups for validation (useful when testing group-based access control) * `--disable-openapi`: Disable OpenAPI file generation during validation ### Check OpenAPI spec Check your OpenAPI file for errors with the following command: ```bash theme={null} mint openapi-check ``` Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`). ### Rename files Rename and update all references to files with the following command: ```bash theme={null} mint rename ``` ### Migrate MDX endpoint pages Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: ```bash theme={null} mint migrate-mdx ``` This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information. ## Formatting While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting. ## Troubleshooting This may be due to an outdated version of Node.js. Try the following: 1. Remove the currently installed version of the mint CLI: `npm uninstall -g mint` 2. Upgrade to Node.js v20.17.0+. 3. Reinstall the mint CLI: `npm install -g mint` **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again. This is due to not having the required permissions to globally install node packages. **Solution**: Try running `sudo npm i -g mint`. When prompted, enter the password that you use to unlock your computer. This is likely due to an outdated version of the CLI. **Solution:** Run `mint update` to get the latest changes. If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine. If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation. If you have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`. 1. Uninstall the old package: ```bash theme={null} npm uninstall -g mintlify ``` 2. Clear your npm cache: ```bash theme={null} npm cache clean --force ``` 3. Reinstall the new package: ```bash theme={null} npm i -g mint ``` If you run `mint version` and the client version displays as `none`, the CLI may be unable to download the client application due to a corporate firewall or VPN blocking the download. **Solution:** Ask your IT administrator to add `releases.mintlify.com` to your network allowlist to enable local development with the CLI. # Introduction Source: https://mintlify-docs.mintlify.app/introduction Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers.

Documentation

Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers and teams.

## Get started with Mintlify Explore the key features that make Mintlify the modern documentation platform for developers and teams. Deploy your first docs site in minutes with our step-by-step guide Install the CLI to preview and develop your docs locally Make quick updates and manage content with our browser-based editor Build rich, interactive documentation with our ready-to-use components ## Why Mintlify? Mintlify combines powerful features with an intuitive developer experience to help you create documentation that users love. Built-in AI assistant, agent, and workflows for reading, writing, and discovering content Modern, responsive design that looks great on any device - no configuration needed Git-based workflow, local development, and support for MDX and OpenAPI Automatic deployments from your repository with preview branches and instant updates # Migrate to Mintlify Source: https://mintlify-docs.mintlify.app/migration Learn how to migrate to Mintlify from Docusaurus, ReadMe, or another platform. This guide helps you move your existing documentation to Mintlify. Choose automated migration for supported platforms or manual migration for complete control over the process. ## Choose your migration path If you are migrating from Docusaurus or ReadMe, use our tools to automate your migration. If you are migrating from any other platform, follow our guide to migrate your content. Migrate your documentation using the [@mintlify/scraping package](https://www.npmjs.com/package/@mintlify/scraping). The package scrapes your content and converts it to use Mintlify components. ### Supported platforms Mintlify provides automated migration tools for the following platforms: Automatically convert your Docusaurus site to Mintlify format Import your ReadMe documentation with full component support If your documentation is hosted on another platform, see the manual migration steps. ### Installing the scraper Install the `@mintlify/scraping` package to get started. ```bash theme={null} npm install @mintlify/scraping@latest -g ``` ### Scraping pages and sections The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default. For large documentation sites, migrate smaller sections one at a time rather than the entire site at once. **Migrate entire sections:** ```bash theme={null} mintlify-scrape section https://your-docs-site.com/docs ``` **Migrate single pages:** ```bash theme={null} mintlify-scrape page https://your-docs-site.com/docs/getting-started ``` **Filter specific paths:** Use the `--filter` (or `-f`) option to scrape only URLs matching a specific path prefix. ```bash theme={null} mintlify-scrape section https://your-docs-site.com --filter=/docs ``` The filter matches the specified path and all nested paths. For example, `--filter=/docs` matches `/docs`, `/docs/getting-started`, `/docs/api/reference`, and so on. You can also use the CLI command: ```bash theme={null} mint scrape site https://your-docs-site.com --filter=/docs ``` **Migrate OpenAPI specifications:** ```bash theme={null} mintlify-scrape openapi-file [openApiFilename] ``` ### Add prepared content to your Mintlify project After scraping your existing documentation platform, you are ready to build your docs on Mintlify. Confirm that all of your pages have been migrated successfully. Review the generated files in the `./docs` directory. Add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository. Push your changes to deploy your migrated documentation to Mintlify. Migrate your documentation from any platform with full control over the process. ### Content migration To migrate your content to Mintlify, you need: * A valid `docs.json` for your site settings and navigation. See [Global settings](/organize/settings) and [Navigation](/organize/navigation) for more information. * A Markdown file (`.md` or `.mdx`) for each page of your documentation. MDX is the recommended format. See [Pages](/organize/pages) for more information. * (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format. Create your `docs.json` referencing the paths to your Markdown pages. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components. ### Asset migration Copy assets to your repository's `images/` directory. Update references in your Markdown files: ```mdx theme={null} ![Alt text](/images/screenshot.png) ``` ## Post-migration checklist After completing your migration (automated or manual), we recommend checking: * All pages render correctly * Navigation works as intended * Internal links resolve properly * Images and assets load correctly * Code blocks display with proper syntax highlighting * Search works * Deployment is configured * Custom domain is set up (if applicable) Test your documentation thoroughly before directing users to your new Mintlify site. # Analytics Source: https://mintlify-docs.mintlify.app/optimize/analytics Track documentation analytics and understand content effectiveness with visitor data. The [analytics](https://dashboard.mintlify.com/products/analytics/v2/) page in your dashboard shows data about visitors to your docs, how they interact with the assistant, what they search for, and their feedback. Use this information to identify which pages are most valuable to your users and track trends over time. ## Filter by AI or human visitors Filter your analytics data by traffic source to analyze AI agent traffic separately from human visitors. The traffic source filter on the analytics page.

The traffic source filter on the analytics page.

When you change the traffic source, the analytics page only displays relevant metrics to that traffic source. For AI traffic, the analytics page only displays visitors and MCP searches. For human traffic, the analytics page displays visitors, assistant insights, searches, and feedback. ## Filter time period Use the range selector to adjust the time period for displayed data. The range selector expanded to show options for viewing different time periods of data.

The range selector expanded to show options for viewing different time periods of data.

## Visitors The visitors tab displays a bar chart of visitors over time, a list of popular pages, and referral sources. Review your visitors analytics to: * **Monitor traffic trends**: Observe changes in traffic after updates or new content to understand the impact of your changes. * **Identify popular pages**: Use popular pages to understand what content is most important to your users so that you can make sure it is up to date and comprehensive. * **Track traffic sources**: Understand where your users are coming from to help you optimize your content for the right audience. ### Top agents When viewing AI traffic, top agents replaces referrals in the visitors tab. Top agents shows which AI agents are visiting your documentation. Use this information to help determine: * **AI agent distribution**: See which AI platforms are accessing your docs to learn which tools your users prefer. * **Integration opportunities**: Identify which AI platforms to prioritize for optimization and testing. * **AI traffic patterns**: Monitor which agents are most active and how their usage changes over time. ## Assistant The assistant tab displays a bar chart of assistant usage over time, a list of categories, and chat history. Review your assistant analytics to: * **Monitor assistant usage**: Observe changes in assistant usage to understand how your users engage with your content. * **Identify frequent categories**: Use high occurrence categories to understand what topics are most important to your users. Identify gaps in coverage and prioritize content updates. * **Review chat history**: Get detailed high intent data about how your users think about your product by reviewing their chat history with the assistant. See what terms they use, what they need help with, and what tasks they try to accomplish. ### Categories The categories tab uses LLMs to automatically group conversations by topic or theme. The categories tab in the assistant analytics page.

The categories tab in the assistant analytics page.

Use categories to identify common topics, patterns in user needs and behavior, and areas where documentation might need expansion or clarification. Click a category row to expand it and view related conversations grouped under that category. Click an individual conversation to view the complete chat thread, including the user's question, the assistant's response, and any sources cited. ### Chat history The chat history tab displays chronological records of all assistant conversations. Click any message to view the complete chat thread, including the user's question, the assistant's response, and any sources cited. ### Export queries For deeper analysis, export a CSV file of your queries, responses, and sources. Use your preferred tools to analyze the exported data. Sample analysis prompts: * List any queries that had no sources cited. * Find patterns in unsuccessful interactions. ## Searches The Searches metric is only available when viewing human traffic. The searches tab displays a bar chart of searches over time and specific queries. Review your searches analytics to: * **Monitor search trends**: Observe changes in search queries to understand how your users are finding your content and what topics they want information on. * **Identify frequent queries**: Use frequent queries to understand what topics are most important to your users. Identify gaps in coverage and prioritize content updates. * **Identify low click through rates**: Click through rates (CTR) show how many users click a search result after typing in a query. Low CTR can indicate that the search results are not relevant to users' queries. If you have frequent search terms with low CTR, consider improving the relevance of search results by adding keywords and updating your content. ## MCP searches The MCP Searches metric is only available when viewing AI traffic. The MCP searches tab displays AI agent search interactions through the Model Context Protocol (MCP). This metric shows how AI agents query and interact with your documentation. Review your MCP searches analytics to: * **Monitor AI search activity**: Track how frequently AI agents search your documentation and identify trends in AI-driven queries. * **Identify common AI queries**: Understand what information AI agents are looking for to optimize your content for AI consumption. * **Improve AI discoverability**: Use frequent MCP search queries to identify gaps in your documentation that AI agents struggle to find answers for. ## Feedback The feedback tab displays a bar chart of feedback over time and specific feedback items. See [Feedback](/optimize/feedback) for more information on using feedback data to improve your content. # Feedback Source: https://mintlify-docs.mintlify.app/optimize/feedback Monitor user satisfaction and feedback on your documentation. To collect and view feedback, you must enable feedback from the [Add-ons](https://dashboard.mintlify.com/products/addons) page in your dashboard. The [feedback](https://dashboard.mintlify.com/products/analytics/v2/feedback) tab displays quantitative thumbs up and thumbs down votes your docs have received and any qualitative feedback that users have provided. Use this information to gauge the quality of your docs and make improvements. View feedback on the analytics page in your dashboard. Feedback tab in the Analytics page.

## Feedback types Contextual and code snippet feedback are in beta. To enable them for your documentation site, [contact our sales team](mailto:hahnbee@mintlify.com). The feedback tab displays information according to the [feedback add-ons](https://dashboard.mintlify.com/products/addons) that you enable. Feedback toggles in the Add-ons page.

* **Thumbs rating**: Simple thumbs up/down voting to gauge overall satisfaction with pages. * **Contextual feedback**: Free form feedback about the content of a page. * **Code snippet feedback**: Feedback specifically on code snippets. * **Edit suggestions**: Allow users to suggest edits to your documentation. Only available for public GitHub repositories. * **Raise issues**: Allow users to create GitHub issues directly from your documentation. Only available for public GitHub repositories. If you disable telemetry in your `docs.json` file, feedback features are not available on your documentation pages. ## Manage feedback For contextual and code snippet feedback, you can set the status of a piece of feedback and add internal notes to track your work resolving user feedback. ### Change feedback status Select the status beside a piece of feedback to mark it as **Pending**, **In Progress**, **Resolved**, or **Dismissed**. Best practices for setting feedback statuses: * **Pending**: Feedback is awaiting review. * **In Progress**: Feedback has been validated and is being worked on. * **Resolved**: Feedback has been resolved. * **Dismissed**: Feedback has been dismissed as not actionable, irrelevant, or inaccurate. ### Filter by status Use the status filter to control which feedback is displayed. Clear a status to hide all feedback with that status. By default, all feedback is displayed. ### Add internal notes Click a piece of feedback to add an internal note. These notes are only visible to people with access to your dashboard. Use notes to add information for collaboration, link relevant support or engineering tickets, or remember any other useful information. ## Use feedback data Review your feedback data to: * **Identify successful content**: Pages with the most positive feedback show what works well in your documentation. * **Prioritize improvements**: Pages with the most negative feedback indicate what content might need attention. * **Take action**: Make documentation updates based on direct user feedback. # PDF exports Source: https://mintlify-docs.mintlify.app/optimize/pdf-exports Export your documentation as a single PDF file. PDF exports are available on [Enterprise plans](https://mintlify.com/pricing). You can export your docs as a single PDF file for offline viewing. The PDF contains all the content in the docs, including images and links, and a navigable table of contents. ## Exporting a PDF Navigate to the [General](https://dashboard.mintlify.com/settings/deployment/general) page in the Project Settings section of your dashboard. Select the **Export all content** button. Optionally, customize the export options: * **Page format**: Choose the page size of the PDF. * **Scale percentage**: Adjust the scale of the PDF. * **Include footer**: Include a footer with the page number and total pages. Select **Export** to start the export process. Once the export is complete, you receive an email with a download link. Click the download link to download the PDF file. # SEO Source: https://mintlify-docs.mintlify.app/optimize/seo Optimize SEO with meta tag configuration for better search visibility. Mintlify automatically handles many SEO best practices, including: * Meta tag generation * Sitemap and `robots.txt` file generation * Semantic HTML structure * Mobile optimization You can fully customize your site's meta tags by adding the `metatags` field to your `docs.json` or a page's frontmatter. ## Automatically generated meta tags Mintlify generates the following meta tags for every page. You can override these meta tags by specifying them in your `docs.json` or a page's frontmatter. **Basic metadata:** * `charset: utf-8` - Character encoding * `og:type: website` - Open Graph type * `og:site_name` - Your documentation site name * `twitter:card: summary_large_image` - Twitter card type **Page-specific metadata:** * `title` - Page title, formatted as "Page Title - Site Name" * `og:title` - Open Graph title, same as page title * `twitter:title` - Twitter title, same as page title * `description` - Page description * `og:description` - Open Graph description, same as page description * `twitter:description` - Twitter description, same as page description **URL and canonical:** * `canonical` - Automatically built from page URL * `og:url` - Set to canonical URL **SEO and indexing:** * `robots` - Generated from page metadata * `noindex` - Generated from page metadata * `keywords` - Generated from page metadata **Images:** * `og:image` - Open Graph image, `og:image:width` set to 1200 and `og:image:height` 630 * `twitter:image` - Twitter image, `twitter:image:width` set to 1200 and `twitter:image:height` 630 **Browser and app metadata:** * `applicationName` - Your documentation site name * `generator: Mintlify` - Identifies the site generator as Mintlify * `apple-mobile-web-app-title` - iOS home screen app name * `msapplication-TileColor` - Windows tile color * Favicons and icons from your config * Sitemap reference link Any meta tags in your `docs.json` `seo.metatags` configuration are also automatically injected into every page, such as `google-site-verification` for search console validation. ## Global meta tags To set default meta tags for all pages, add the `metatags` field to your `docs.json`. ```json theme={null} "seo": { "metatags": { "og:image": "link to your default meta tag image" } } ``` ### Set a canonical URL If you're using a custom domain, set the `canonical` meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content. ```json theme={null} "seo": { "metatags": { "canonical": "https://www.your-custom-domain-here.com" } } ``` ## Page-specific meta tags To set page-specific meta tags, add them to a page's frontmatter. Page-specific meta tags include: * `title` - Page title * `description` - Page description appears below the title on the page and in some search engine results * `keywords` - Comma-separated keywords * `og:title` - Open Graph title for social sharing * `og:description` - Open Graph description * `og:image` - Open Graph image URL * `og:url` - Open Graph URL * `og:type` - Open Graph type like "article" or "website" * `og:image:width` - Open Graph image width * `og:image:height` - Open Graph image height * `twitter:title` - Twitter card title * `twitter:description` - Twitter card description * `twitter:image` - Twitter card image * `twitter:card` - Twitter card type like `summary` or `summary_large_image` * `twitter:site` - Twitter site handle * `twitter:image:width` - Twitter image width * `twitter:image:height` - Twitter image height * `noindex` - Set to `true` to prevent search engine indexing * `robots` - Robots meta tag value ```mdx theme={null} --- title: "Your example page title" description: "Page-specific description" "og:image": "link to your meta tag image" "og:title": "Social media title" keywords: ["keyword1", "keyword2"] --- ``` You must wrap meta tags with colons in quotes. For example, `og:title: "Social media title"`. You must format the `keywords` field as a YAML array. For example, `keywords: ["keyword1", "keyword2", "keyword3"]`. ## Common meta tags reference Below is a comprehensive list of meta tags you can add to your `docs.json`. These meta tags help improve your site's SEO, social sharing, and browser compatibility. The `og:image` adds a background image that Mintlify automatically overlays with your logo, page title, and description when generating social media previews. You can preview how your meta tags appear on different platforms using [metatags.io](https://metatags.io/). ```json expandable theme={null} "seo": { "metatags": { "robots": "noindex", "charset": "UTF-8", "viewport": "width=device-width, initial-scale=1.0", "description": "Page description", "keywords": "keyword1, keyword2, keyword3", "author": "Author Name", "robots": "index, follow", "googlebot": "index, follow", "google": "notranslate", "google-site-verification": "verification_token", "generator": "Mintlify", "theme-color": "#000000", "color-scheme": "light dark", "canonical": "https://your-custom-domain-here.com", "format-detection": "telephone=no", "referrer": "origin", "refresh": "30", "rating": "general", "revisit-after": "7 days", "language": "en", "copyright": "Copyright 2024", "reply-to": "email@example.com", "distribution": "global", "coverage": "Worldwide", "category": "Technology", "target": "all", "HandheldFriendly": "True", "MobileOptimized": "320", "apple-mobile-web-app-capable": "yes", "apple-mobile-web-app-status-bar-style": "black", "apple-mobile-web-app-title": "App Title", "application-name": "App Name", "msapplication-TileColor": "#000000", "msapplication-TileImage": "path/to/tile.png", "msapplication-config": "path/to/browserconfig.xml", "og:title": "Open Graph Title", "og:type": "website", "og:url": "https://example.com", "og:image": "https://example.com/image.jpg", "og:description": "Open Graph Description", "og:site_name": "Site Name", "og:locale": "en_US", "og:video": "https://example.com/video.mp4", "og:audio": "https://example.com/audio.mp3", "twitter:card": "summary", "twitter:site": "@username", "twitter:creator": "@username", "twitter:title": "Twitter Title", "twitter:description": "Twitter Description", "twitter:image": "https://example.com/image.jpg", "twitter:image:alt": "Image Description", "twitter:player": "https://example.com/player", "twitter:player:width": "480", "twitter:player:height": "480", "twitter:app:name:iphone": "App Name", "twitter:app:id:iphone": "12345", "twitter:app:url:iphone": "app://", "article:published_time": "2024-01-01T00:00:00+00:00", "article:modified_time": "2024-01-02T00:00:00+00:00", "article:expiration_time": "2024-12-31T00:00:00+00:00", "article:author": "Author Name", "article:section": "Technology", "article:tag": "tag1, tag2, tag3", "book:author": "Author Name", "book:isbn": "1234567890", "book:release_date": "2024-01-01", "book:tag": "tag1, tag2, tag3", "profile:first_name": "John", "profile:last_name": "Doe", "profile:username": "johndoe", "profile:gender": "male", "music:duration": "205", "music:album": "Album Name", "music:album:disc": "1", "music:album:track": "1", "music:musician": "Artist Name", "music:song": "Song Name", "music:song:disc": "1", "music:song:track": "1", "video:actor": "Actor Name", "video:actor:role": "Role Name", "video:director": "Director Name", "video:writer": "Writer Name", "video:duration": "120", "video:release_date": "2024-01-01", "video:tag": "tag1, tag2, tag3", "video:series": "Series Name" } } ``` ## Sitemaps and robots.txt files Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. You can view your sitemap by appending `/sitemap.xml` to your documentation site's URL. Only pages included in your `docs.json` are included by default. To include hidden links, add `seo.indexing` to your `docs.json`: ```json theme={null} "seo": { "indexing": "all" } ``` ### Custom sitemaps and robots.txt files To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `robots.txt` file at the root of your project. Adding a custom file overrides the automatically generated file of the same name. If you delete a custom file, the default file automatically applies again. ## Disable indexing To prevent search engines from indexing a page, add `noindex: true` to the [frontmatter](/organize/pages) of the page. ```yaml theme={null} --- noindex: true --- ``` Pages with `hidden: true` in their frontmatter are automatically treated as `noindex: true`. See [Hidden pages](/organize/hidden-pages) for more details. You can also specify `noindex` for all pages in your docs by setting the `metatags.robots` field to `"noindex"` in your `docs.json`: ```json theme={null} "seo": { "metatags": { "robots": "noindex" } } ``` ## SEO best practices * Use clear, descriptive page titles (50-60 characters) * Write compelling descriptions (150-160 characters) * Include relevant keywords * Make each page title and description unique * Use proper heading hierarchy (H1 → H2 → H3) * Write for humans first, search engines second * Include relevant keywords in headings and content * Keep URLs short, descriptive, and organized hierarchically * Break up long content with subheadings and lists * Link to related pages within your documentation * Use descriptive anchor text instead of "click here" * Create topic clusters by linking related concepts * Use the automatic cross-referencing features * Use descriptive filenames for images * Always include alt text for accessibility and SEO * Optimize image file sizes for faster loading * Use relevant images that support your content # Hidden pages Source: https://mintlify-docs.mintlify.app/organize/hidden-pages Hide pages from your navigation while keeping them accessible. Hidden pages don't appear in your site's navigation, but anyone who knows the URL can still access them. Use hidden pages for content you want users to access or reference as context for AI tools, but don't want listed in the navigation. For example, if you create a hidden page like `guides/hidden-page.mdx`, visitors can reach it at `docs.yoursite.com/guides/hidden-page`. If your content requires strict access control, you must configure [authentication](/deploy/authentication-setup). To restrict pages to specific user groups, set up [group-based access control](/deploy/authentication-setup#control-access-with-groups). Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages. ## Hide a page To hide a page, set `hidden: true` in the page's frontmatter or remove it from your `docs.json` navigation. ### Set hidden: true in frontmatter Add `hidden: true` to a page's frontmatter to remove it from the rendered navigation while still including it in your `docs.json` configuration. ```yaml theme={null} --- title: "My hidden page" hidden: true --- ``` Search engines cannot index hidden pages. When you set `hidden: true`, the page is automatically excluded from search engine indexing, sitemaps, and AI context. However, setting `noindex: true` does **not** hide a page from navigation. See [Disable indexing](/optimize/seo#disable-indexing) for more information. ### Remove the page from navigation If you don't include a page in your `docs.json` navigation, you hide it. This method works well for pages that you don't want to appear in navigation at all. ## Hide a group of pages To hide a group of pages, set the `hidden` property to `true` for the group in your `docs.json` file: ```json theme={null} "groups": [ { "group": "Getting started", "hidden": true, "pages": [ "index", "quickstart" ] }, { "group": "Guides", "pages": [ "guides/hidden-page.mdx", "guides/hidden-groups.mdx" ] } ] ``` In this example, the `Getting started` group is hidden and the `Guides` group is visible. ### Hide a tab To hide a tab, add the `hidden` property for the tab in your `docs.json` file: ```json theme={null} "tabs": [ { "tab": "Home", "hidden": true, "pages": [ "index", "quickstart" ] } ] ``` ## Search, SEO, and AI indexing By default, hidden pages don't appear in indexing for search engines, documentation site search, or as AI assistant context. To include hidden pages in search results and assistant context, add the `seo` property to your `docs.json`: ```json theme={null} "seo": { "indexing": "all" } ``` ### Understanding hidden versus noindex The relationship between `hidden` and `noindex` is one-directional: ```text hidden: true → automatically applies noindex theme={null} Hidden pages are automatically excluded from search engines, sitemaps, and AI context. ``` ```text noindex: true → does NOT apply hidden theme={null} Pages with noindex: true remain visible in navigation. They only affect search engine indexing and AI context. ``` To exclude a specific page from search engines while keeping it visible in navigation, add `noindex: true` to its frontmatter. To hide a page from navigation and search engines, use `hidden: true`. # Navigation Source: https://mintlify-docs.mintlify.app/organize/navigation Design information architecture that aligns with user needs. The `navigation` property in `docs.json` controls the structure and information hierarchy of your documentation. With proper navigation configuration, you can organize your content so that users can find exactly what they're looking for. Choose one primary organizational pattern at the root level of your navigation. Once you've chosen your primary pattern, you can nest other navigation elements within it. ## Pages Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. In the `navigation` object, `pages` is an array where each entry must reference the path to a page file. ```json theme={null} { "navigation": { "pages": [ "settings", "pages", "navigation", "themes", "custom-domain" ] } } ``` ## Groups Use groups to organize your sidebar navigation into sections. You can nest groups within each other, label them with tags, and style them with icons. In the `navigation` object, `groups` is an array where each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, and `expanded` fields are optional. ```json theme={null} { "navigation": { "groups": [ { "group": "Getting started", "icon": "play", "pages": [ "quickstart", { "group": "Editing", "expanded": false, "icon": "pencil", "pages": [ "installation", "editor" ] } ] }, { "group": "Writing content", "icon": "notebook-text", "tag": "NEW", "pages": [ "writing-content/page", "writing-content/text" ] } ] } } ``` ### Root page Use the `root` property to designate a main page for a group. When a group has a root page, clicking the group title in the sidebar navigation opens the root page. ```json theme={null} { "navigation": { "groups": [ { "group": "API pages", "root": "api-overview", "pages": [ "api-reference/get", "api-reference/post", "api-reference/delete" ] } ] } } ``` ### Default expanded state Use the `expanded` property to control the default state of a nested group in the navigation sidebar. The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed. ```json theme={null} { "group": "Getting started", "pages": [ "quickstart", { "group": "Advanced", "expanded": false, "pages": ["installation", "configuration"] } ] } ``` ## Tabs Tabs create distinct sections of your documentation with separate URL paths. Tabs create a horizontal navigation bar at the top of your documentation that lets users switch between sections. In the `navigation` object, `tabs` is an array where each entry is an object that requires a `tab` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. ```json theme={null} { "navigation": { "tabs": [ { "tab": "API reference", "icon": "square-terminal", "pages": [ "api-reference/get", "api-reference/post", "api-reference/delete" ] }, { "tab": "SDKs", "icon": "code", "pages": [ "sdk/fetch", "sdk/create", "sdk/delete" ] }, { "tab": "Blog", "icon": "newspaper", "href": "https://external-link.com/blog" } ] } } ``` ### Menus Menus add dropdown navigation items to a tab. Use menus to help users go directly to specific pages within a tab. Menu items can only contain groups, pages, and external links. ```json theme={null} { "navigation": { "tabs": [ { "tab": "Developer tools", "icon": "square-terminal", "menu": [ { "item": "API reference", "icon": "rocket", "groups": [ { "group": "Core endpoints", "icon": "square-terminal", "pages": [ "api-reference/get", "api-reference/post", "api-reference/delete" ] } ] }, { "item": "SDKs", "icon": "code", "description": "SDKs are used to interact with the API.", "pages": [ "sdk/fetch", "sdk/create", "sdk/delete" ] } ] } ] } } ``` ## Anchors Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action. In the `navigation` object, `anchors` is an array where each entry is an object that requires an `anchor` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. ```json theme={null} { "navigation": { "anchors": [ { "anchor": "Documentation", "icon": "book-open", "pages": [ "quickstart", "development", "navigation" ] }, { "anchor": "API reference", "icon": "square-terminal", "pages": [ "api-reference/get", "api-reference/post", "api-reference/delete" ] }, { "anchor": "Blog", "href": "https://external-link.com/blog" } ] } } ``` ### Global anchors Use global anchors for links that should appear on all pages, regardless of which section of your navigation the user is viewing. Global anchors are particularly useful for linking to resources outside your documentation (such as a blog, community forum, or support portal) or for providing consistent access to important internal pages (such as a changelog or status page). ```json theme={null} { "navigation": { "global": { "anchors": [ { "anchor": "Changelog", "icon": "list", "href": "/changelog" }, { "anchor": "Blog", "icon": "pencil", "href": "https://mintlify.com/blog" } ] }, "tabs": [] } } ``` ## Dropdowns Dropdowns are an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation. In the `navigation` object, `dropdowns` is an array where each entry is an object that requires a `dropdown` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. ```json theme={null} { "navigation": { "dropdowns": [ { "dropdown": "Documentation", "icon": "book-open", "pages": [ "quickstart", "development", "navigation" ] }, { "dropdown": "API reference", "icon": "square-terminal", "pages": [ "api-reference/get", "api-reference/post", "api-reference/delete" ] }, { "dropdown": "Blog", "href": "https://external-link.com/blog" } ] } } ``` ## Products Products create a dedicated navigation division for organizing product-specific documentation. Use products to separate different offerings, services, or major feature sets within your documentation. In the `navigation` object, `products` is an array where each entry is an object that requires a `product` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. ```json theme={null} { "navigation": { "products": [ { "product": "Core API", "description": "Core API description", "icon": "api", "groups": [ { "group": "Getting started", "pages": [ "core-api/quickstart", "core-api/authentication" ] }, { "group": "Endpoints", "pages": [ "core-api/users", "core-api/orders" ] } ] }, { "product": "Analytics Platform", "description": "Analytics Platform description", "icon": "chart-bar", "pages": [ "analytics/overview", "analytics/dashboard", "analytics/reports" ] }, { "product": "Mobile SDK", "description": "Mobile SDK description", "icon": "smartphone", "href": "https://mobile-sdk-docs.example.com" } ] } } ``` ## OpenAPI Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification. To control which endpoints appear, explicitly list the desired endpoints in a `pages` array. For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup). ```json theme={null} { "navigation": { "groups": [ { "group": "API reference", "openapi": "/path/to/openapi-v1.json", "pages": [ "overview", "authentication", "GET /users", "POST /users", { "group": "Products", "openapi": "/path/to/openapi-v2.json", "pages": [ "GET /products", "POST /products" ] } ] } ] } } ``` ## Versions Partition your navigation into different versions. Versions are selectable from a dropdown menu. In the `navigation` object, `versions` is an array where each entry is an object that requires a `version` field and can contain any other navigation fields. ```json theme={null} { "navigation": { "versions": [ { "version": "1.0.0", "groups": [ { "group": "Getting started", "pages": ["v1/overview", "v1/quickstart", "v1/development"] } ] }, { "version": "2.0.0", "groups": [ { "group": "Getting started", "pages": ["v2/overview", "v2/quickstart", "v2/development"] } ] } ] } } ``` ### Version tags Add a badge label to version entries in the version selector dropdown using the optional `tag` field. Use tags to highlight specific versions such as "Latest", "Recommended", or "Beta." ```json theme={null} { "navigation": { "versions": [ { "version": "2026_03", "tag": "Latest", "groups": [ { "group": "Getting started", "pages": ["getting-started", "quickstart"] } ] }, { "version": "2025_12", "tag": "Recommended", "groups": [ { "group": "Getting started", "pages": ["2025_12/getting-started", "2025_12/quickstart"] } ] } ] } } ``` ## Languages Partition your navigation into different languages. Languages are selectable from a dropdown menu. In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields, including language-specific banner configurations. ```json theme={null} { "navigation": { "languages": [ { "language": "en", "banner": { "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.", "dismissible": true }, "groups": [ { "group": "Getting started", "pages": ["en/overview", "en/quickstart", "en/development"] } ] }, { "language": "es", "banner": { "content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog).", "dismissible": true }, "groups": [ { "group": "Getting started", "pages": ["es/overview", "es/quickstart", "es/development"] } ] } ] } } ``` For automated translations, contact the Mintlify sales team to discuss solutions. ## Breadcrumbs Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. ```json Display full breadcrumbs theme={null} "styling": { "eyebrows": "breadcrumbs" } ``` ```json Display parent section only theme={null} "styling": { "eyebrows": "section" } ``` ## Interaction configuration Control how users interact with navigation elements using the `interaction` property in your `docs.json`. ### Enable auto-navigation for groups When a user expands a navigation group, some themes automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option. ```json Force navigation theme={null} "interaction": { "drilldown": true } ``` ```json Prevent navigation theme={null} "interaction": { "drilldown": false } ``` * Set to `true` to force automatic navigation to the first page when a user selects a navigation group. * Set to `false` to prevent navigation and only expand or collapse the group when a user selects a navigation group. * Leave unset to use the theme's default behavior. # Pages Source: https://mintlify-docs.mintlify.app/organize/pages Configure page metadata, titles, and frontmatter properties. Each page is a Markdown file. You can use either `.mdx` or `.md` file types for your pages. We recommend MDX, which combines Markdown with React components for rich, interactive documentation. Plain Markdown (`.md`) can expedite migration from other platforms, but switching to MDX enables more features. ## Page metadata Every page begins with frontmatter, the YAML metadata enclosed by `---` at the top of a file. This metadata controls how your page appears and behaves. Use frontmatter to control: * Page titles and descriptions * Sidebar titles, icons, and tags * Page layouts * SEO meta tags * Custom metadata ### Basic frontmatter ```yaml theme={null} --- title: "About frontmatter" description: "Frontmatter is the metadata that controls how your page appears and behaves" sidebarTitle: "Frontmatter" icon: "book" tag: "NEW" --- ``` ### Frontmatter fields **title** (required) The title of your page that appears in navigation and browser tabs. **description** A brief description of what this page covers. Displays under the title and improves SEO. **sidebarTitle** A short title that displays in the sidebar navigation. **icon** The icon to display. Options: * Font Awesome icon name * Lucide icon name * Tabler icon name * URL to an externally hosted icon * Path to an icon file in your project **iconType** For Font Awesome icons only. The style of the icon. Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. **tag** A tag that appears next to your page title in the sidebar. **hidden** Set to `true` to remove the page from the sidebar navigation. Users can still access the page via its URL, but search engines do not index it. See [Hidden pages](/organize/hidden-pages) for details. **noindex** Set to `true` to prevent search engines from indexing the page. See [Disable indexing](/optimize/seo#disable-indexing) for details. All pages with `hidden: true` in their frontmatter receive `noindex: true` automatically. ## Page mode Control your page's layout with the `mode` setting. ### Default If you do not define a mode, the page uses a standard layout with sidebar navigation and table of contents. ```yaml theme={null} --- title: "Default page title" --- ``` ### Wide Wide mode hides the table of contents. Use this mode for pages without headings or if you want extra horizontal space. ```yaml theme={null} --- title: "Wide page title" mode: "wide" --- ``` Every theme supports wide mode. ### Custom Custom mode provides a minimalist layout and removes all elements except for the top navbar. Treat custom mode as a blank canvas to build landing pages or unique layouts with minimal navigation. ```yaml theme={null} --- title: "Custom page title" mode: "custom" --- ``` The `style` property on custom mode pages may cause a layout shift on page load. Prefer Tailwind CSS or custom CSS to avoid this issue. ### Frame Frame mode provides a layout similar to custom mode but keeps the sidebar navigation. Use this mode to include custom HTML and components while preserving the default navigation experience. ```yaml theme={null} --- title: "Frame page title" mode: "frame" --- ``` Only Aspen, Almond, and Luma themes support frame mode. ### Center Center mode removes the sidebar and table of contents, and centers the content. Use center mode for changelogs or other pages where you want to place focus on the content. ```yaml theme={null} --- title: "Center page title" mode: "center" --- ``` Mint and Linden themes support center mode. ## API pages To create an interactive API playground, add an API specification to your frontmatter by setting `api` or `openapi`. ```yaml theme={null} --- openapi: "GET /endpoint" --- ``` Learn more about building [API documentation](/api-playground/overview). ## External links Link to external sites directly from your navigation with the `url` metadata. ```yaml theme={null} --- title: "npm Package" url: "https://www.npmjs.com/package/mint" --- ``` ## Search engine optimization Mintlify automatically generates most SEO meta tags. You can set SEO meta tags manually to customize your approach to SEO, social sharing, and browser compatibility. Always wrap meta tags with colons in quotes. ```yaml theme={null} --- "twitter:image": "/images/social-preview.jpg" --- ``` See [SEO](/optimize/seo) for the full list of SEO metadata options. ## Internal search keywords Help users discover a specific page in search results by providing `keywords` in your metadata. These keywords don't appear in page content. If users search for the keywords, the page appears in the search results. ```yaml theme={null} --- keywords: ['configuration', 'setup', 'getting started'] --- ``` ## Last modified timestamp Show a "Last modified on \[date]" timestamp on all pages by enabling `metadata.timestamp` in your global settings. ```json docs.json theme={null} "metadata": { "timestamp": true } ``` To override the global timestamp setting for an individual page, use the `timestamp` frontmatter field. ```yaml theme={null} --- title: "Page title" timestamp: false --- ``` If you set `timestamp: true`, the page always shows the timestamp even if the global setting is `false`. If you set `timestamp: false`, the page hides the timestamp even if the global setting is `true`. # Global settings Source: https://mintlify-docs.mintlify.app/organize/settings Configure site-wide settings in docs.json. The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. Think of it as the blueprint for your documentation. Settings in `docs.json` apply globally to all pages. ## Setting up your docs.json To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow. For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors. ```json theme={null} { "$schema": "https://mintlify.com/docs.json", "theme": "mint", "name": "Your Docs", "colors": { "primary": "#ff0000" }, "navigation": { // Your navigation structure } // The rest of your configuration } ``` ## Customization ### Theme The layout theme of your site. Choose from: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`, `sequoia`, `luma`. See the [Themes documentation](/customize/themes) for more information. ### Name The name of your project, organization, or product. ### Colors The colors used in your documentation. Colors are applied differently across themes. ```json Primary color only theme={null} "colors": { "primary": "#3B82F6" } ``` ```json Multiple colors theme={null} "colors": { "primary": "#3B82F6", "light": "#F8FAFC", "dark": "#0F172A" } ``` All color values must be hex codes beginning with `#`. ### Logo Set your logo for both light and dark mode. ```json theme={null} "logo": { "light": "/logo.png", "dark": "/logo-dark.png", "href": "https://mintlify.com" } ``` ### Favicon Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. ```json Single favicon theme={null} "favicon": "/favicon.png" ``` ```json Light and dark favicons theme={null} "favicon": { "light": "/favicon.png", "dark": "/favicon-dark.png" } ``` ### Fonts Set custom fonts for your documentation. The default font varies by theme. ```json theme={null} "fonts": { "family": "Open Sans", "weight": 400, "heading": { "family": "Playfair Display", "weight": 700 }, "body": { "family": "Open Sans", "weight": 400 } } ``` Supports [Google Fonts](https://fonts.google.com) family names. Google Fonts are loaded automatically when you specify a family name. ### Background Background color and decoration settings. ```json theme={null} "background": { "decoration": "gradient", "color": { "light": "#ffffff", "dark": "#000000" }, "image": { "light": "/background.png", "dark": "/background-dark.png" } } ``` ### Variables Global variables for use throughout your documentation. Variables are replaced at build time using `{{variableName}}` syntax. ```json theme={null} "variables": { "version": "2.0.0", "api-url": "https://api.example.com" } ``` All variables referenced in your content must be defined, or the build will fail. ## Navigation The navigation structure of your content. See [Navigation](/organize/navigation) for detailed information. ```json theme={null} "navigation": { "groups": [ { "group": "Getting started", "pages": [ "index", "quickstart" ] } ] } ``` ## Integrations Third-party integrations for analytics, chat, and more. ### Analytics integrations ```json Google Analytics 4 theme={null} "integrations": { "ga4": { "measurementId": "G-XXXXXXXXXX" } } ``` ```json Mixpanel theme={null} "integrations": { "mixpanel": { "projectToken": "your-project-token" } } ``` ```json PostHog theme={null} "integrations": { "posthog": { "apiKey": "phc_your-api-key", "apiHost": "https://app.posthog.com" } } ``` ### Chat integrations ```json Intercom theme={null} "integrations": { "intercom": { "appId": "your-app-id" } } ``` ```json Front Chat theme={null} "integrations": { "frontchat": { "snippetId": "your-snippet-id" } } ``` ### Telemetry ```json theme={null} "integrations": { "telemetry": { "enabled": true } } ``` When set to `false`, feedback features are also disabled and do not appear on your documentation pages. ## SEO and search ### SEO configuration ```json theme={null} "seo": { "indexing": "navigable", "metatags": { "og:image": "https://example.com/image.png" } } ``` Choose `navigable` to index only pages in your navigation or `all` to index every page. Defaults to `navigable`. ### Search settings ```json theme={null} "search": { "prompt": "Search documentation..." } ``` ## API configurations API documentation and interactive playground settings. ```json theme={null} "api": { "openapi": "openapi.json", "playground": { "display": "interactive" }, "examples": { "languages": ["javascript", "python", "curl"] } } ``` See [API Playground](/api-playground/overview) for more information. ## Footer Footer content and social media links. ```json theme={null} "footer": { "socials": { "x": "https://x.com/mintlify", "github": "https://github.com/mintlify", "linkedin": "https://linkedin.com/company/mintlify" }, "links": [ { "header": "Resources", "items": [ { "label": "Blog", "href": "https://mintlify.com/blog" } ] } ] } ``` ## Navbar Navigation bar items to external links. ```json theme={null} "navbar": { "links": [ { "type": "github", "href": "https://github.com/example/repo" }, { "label": "Community", "href": "https://example.com/community" } ], "primary": { "type": "button", "label": "Get Started", "href": "https://example.com/start" } } ``` ## Metadata Metadata configuration for documentation pages. ```json theme={null} "metadata": { "timestamp": true } ``` Enable the last modified date on all pages. You can override this setting on individual pages with the `timestamp` frontmatter field. ## Banner Site-wide banner displayed at the top of pages. ```json theme={null} "banner": { "content": "🚀 Banner is live! [Learn more](https://mintlify.com)", "dismissible": true } ``` ## Redirects Redirects for moved, renamed, or deleted pages. ```json theme={null} "redirects": [ { "source": "/old-page", "destination": "/new-page", "permanent": true } ] ``` ## Error handling 404 error page customization. ```json theme={null} "errors": { "404": { "redirect": false, "title": "Page not found", "description": "The page you're looking for doesn't exist." } } ``` # Quickstart Source: https://mintlify-docs.mintlify.app/quickstart Deploy your documentation site and make your first change. After you complete this guide, you'll have a live documentation site ready to customize and update. ## Before you begin Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository. When you connect your documentation repository to your project, you can work on your documentation locally or in the web editor and sync any changes to your remote repository. Using an AI coding tool? Copy the prompt below to add the Mintlify [skill](/ai/skillmd) and [MCP server](/ai/model-context-protocol) for better results when updating your documentation. Install the Mintlify skill to get context on Mintlify project structure, components, and documentation best practices: npx skills add [https://mintlify.com/docs](https://mintlify.com/docs) Then add the Mintlify MCP server for access to documentation search. Follow the setup instructions at [https://www.mintlify.com/docs/ai/model-context-protocol.md](https://www.mintlify.com/docs/ai/model-context-protocol.md) ## Deploy your documentation site Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding process. During onboarding, you'll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments. After onboarding, your documentation site is deployed and accessible at your `.mintlify.app` URL. If you want to get started quickly without connecting your own repository, you can skip the GitHub connection during onboarding. Mintlify creates a private repository in a private organization and automatically configures the GitHub App for you. This lets you use the web editor immediately and migrate to your own repository later. ## View your deployed site Your documentation site is now deployed at `https://.mintlify.app`. Find your exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/). Overview page of the Mintlify dashboard.

Overview page of the Mintlify dashboard.

Your site is ready to view immediately. Use this URL for testing and sharing with your team. Before sharing with your users, you may want to add a [custom domain](/customize/custom-domain). ## Make your first change The CLI requires [Node.js](https://nodejs.org/en) v20.17.0 or higher. Use an LTS version for stability. ```bash npm theme={null} npm i -g mint ``` ```bash pnpm theme={null} pnpm add -g mint ``` See [Install the CLI](/installation) for full details and troubleshooting. If you haven't already cloned your repository locally, follow the instructions in [Clone your repository](/installation#clone-your-repository). Open `index.mdx` in your preferred editor and update the description in the frontmatter: ```mdx theme={null} --- title: "Introduction" description: "Your custom description here" --- ``` Run the following command from your documentation directory: ```bash theme={null} mint dev ``` View your preview at `http://localhost:3000`. Commit and push your changes to trigger a deployment: ```bash theme={null} git add . git commit -m "Update description" git push ``` Mintlify automatically deploys your changes. View your deployment status on the [Overview](https://dashboard.mintlify.com/) page of your dashboard. Navigate to the [web editor](https://dashboard.mintlify.com/editor) in your dashboard. Open the **Introduction** page and update the description. Introduction page open in the web editor with the description edited to say Hello world!.

Introduction page open in the web editor with the description edited to say Hello world!.

Click the **Publish** button in the top-right of the web editor toolbar. On the [Overview](https://dashboard.mintlify.com/) page of your dashboard, you can see your site's deployment status. When it finishes deploying, refresh your documentation site to see your changes live. ## Next steps Edit documentation in your browser and preview how your pages look when published. Find broken links, check accessibility, validate OpenAPI specs, and more. Use your own domain for your documentation site. # What is Mintlify? Source: https://mintlify-docs.mintlify.app/what-is-mintlify Mintlify is a knowledge platform for hosting information designed for people and AI. Mintlify hosts your content as a website. Your content lives in a Git repository as MDX files, and Mintlify builds and deploys your site automatically when you push a change. ## The three parts of a Mintlify project **Your repository** is the source of truth for your documentation. It contains an MDX file for every page and a `docs.json` file that configures your site's navigation, theme, and settings. You can use your own GitHub or GitLab repository, or let Mintlify create one for you during onboarding. **The Mintlify dashboard** connects to your repository and lets you manage your site. Use it to monitor deployments, configure settings, manage your team, and edit content directly in the browser. **Your site** powered by Mintlify. Mintlify builds your site from your repository and deploys it at a `.mintlify.app` URL by default. When you're ready, you can point a custom domain to your site. ```mermaid theme={null} flowchart LR WE["Web editor"] --> Repo[("Git repository")] Local["Local editor"] --> Repo Repo -- "Webhook" --> Build["Mintlify build"] Build --> Site["Live site"] ``` ## Editing content There are two ways to edit your content, and you can switch between them freely. Edit and publish pages in your browser. The editor commits changes back to your Git repository automatically. Clone your repository, run `mint dev` to preview your site locally, then push changes to deploy. Multiple team members can work in either workflow at the same time, using Git branches to manage parallel changes. Anyone who can push to your repository can update your content. ## AI features Built-in AI features help people and AI find and understand your content, and help you maintain your content. The **assistant** lets your users ask questions and get cited answers from your content. The **agent** helps your team create and maintain content by generating updates from scheduled workflows, pull requests merging in your feature repository, or Slack threads. See [AI-native documentation](/ai-native) for an overview of all AI features. ## Next steps Deploy your first documentation site in minutes.

Hello, world!

Header without anchor link

Documentation