# Customize agent behavior
Source: https://www.mintlify.com/docs/agent/customize
Customize agent behavior with an `AGENTS.md` configuration file to control how the agent handles documentation tasks and follows your conventions.
Create a `.mintlify/AGENTS.md` file at the root of your documentation project to customize the agent's behavior (`Agents.md` is also an accepted filename).
Place your `AGENTS.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible by the `/agents.md` path. The `.mintlify/` directory is not served publicly so your `AGENTS.md` file is not accessible when in that directory.
If you must store your `AGENTS.md` file at the root of your project or any other directory, add it to your [`.mintignore`](/organize/mintignore) file to exclude it from your documentation site.
Add any instructions that you want the agent to follow. The agent appends these instructions to its system prompt, so the instructions apply to all tasks whether you use the agent in your dashboard, on Slack, or via the API.
## What to include in AGENTS.md
Consider adding instructions for:
* **Style preferences**: Voice, tone, formatting, and terminology specific to your documentation.
* **Code standards**: Programming languages, frameworks, and coding conventions to use in examples.
* **Content requirements**: What sections or information to include for different types of pages.
* **Project context**: Specific details about your product, architecture, or user base that inform documentation decisions.
## Example AGENTS.md file
```markdown .mintlify/AGENTS.md theme={null}
# Documentation agent instructions
## Code examples
- Use TypeScript for all code examples. Our users are primarily TypeScript developers.
- Always include error handling in API call examples.
- Show both success and error response examples for all endpoints.
- Include import statements at the top of code examples.
## API documentation standards
- Every endpoint must document: authentication requirements, rate limits, and common error codes.
- Use real-world parameter values in examples (not foo/bar placeholders).
- Include a complete request/response cycle for each endpoint.
## Style and formatting
- Write for developers with 2-5 years of experience. Don't oversimplify, but explain non-obvious concepts.
- Use active voice and second person ("you").
- Date format: ISO 8601 (YYYY-MM-DD).
- When referencing UI elements, use bold: **Settings** button.
## What to include
- Add prerequisite sections to guides when users need API keys, environment setup, or dependencies.
- Include "Next steps" sections linking to related documentation.
- Add troubleshooting sections for common issues we see in support tickets.
```
# Write effective prompts
Source: https://www.mintlify.com/docs/agent/effective-prompts
Write clear, specific prompts to get better results from the Mintlify agent, with examples of effective instructions and tips for common patterns.
Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps.
## Make prompts specific and outcome-focused
Generic prompts like `@mintlify Improve the onboarding page` apply general best practices, but may not improve content in the specific way that you were picturing.
Try prompts based on outcomes you want your users to achieve or problems that they encounter.
* `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI`
* `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`
## Use broad prompts for maintenance tasks
Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs.
* `@mintlify Find and fix all typos in the docs`
* `@mintlify change all unordered lists to use * instead of -`
## Specify a domain name for multi-site organizations
If you have multiple documentation sites, include the `subdomain` parameter in your message to specify which documentation set the agent should work on.
To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`.
Use the format `@mintlify subdomain=` to prompt the agent to work on a specific documentation set.
* `@mintlify subdomain=public-docs Add a new section to the quickstart about inviting collaborators based on this PR`: Prompts the agent to update the quickstart only on the `public-docs` site.
* `@mintlify subdomain=customer-docs Update the auth docs for the new authentication method`: Prompts the agent to update the auth docs only on the `customer-docs` site.
# What is the agent?
Source: https://www.mintlify.com/docs/agent/index
Automate documentation updates with the Mintlify agent. Trigger changes from Slack messages, pull requests, Linear issues, or API calls.
The agent is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent).
The agent is an AI tool that creates pull requests with proposed changes to your documentation based on your prompts. When you send a request, the agent:
* **Researches**: Searches and reads your existing documentation, any connected repositories, and relevant context.
* **Plans**: Creates a structured task list for complex documentation work.
* **Writes**: Generates or updates content following writing standards and best practices.
* **Validates**: Runs Mintlify CLI checks to ensure documentation builds correctly.
* **Creates a PR**: Opens a pull request with proposed changes for review.
All changes go through pull requests. The agent never commits directly to your main branch.
## What you can do with the agent
Use the agent to:
* Write new content based on your prompts, pull requests, Linear issues, Slack threads, or file attachments.
* Update existing documentation for new features or API changes.
* Process and include images, diagrams, and other files from Slack attachments.
* Search and revise code examples and API references across your docs.
* Automate documentation maintenance with workflows.
* Answer questions about your docs and technical writing topics.
* Address code review feedback to maintain documentation quality.
* Capture knowledge from Slack conversations and pull requests before it gets lost.
* Navigate and coordinate changes across multiple files and directories efficiently.
## Connect your GitHub account
By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://dashboard.mintlify.com/settings/account) page of the dashboard.
## Connect repositories as context
The agent can only access repositories that you connect through the Mintlify GitHub App. Configure which repositories the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
## Next steps
Add the agent to your Slack workspace.
Add the agent to your Linear workspace.
Give the agent access to your Notion workspace.
Configure the agent with an `AGENTS.md` file.
Get better results with focused prompts.
Automate recurring tasks and documentation maintenance with workflows.
# Add the agent to Linear
Source: https://www.mintlify.com/docs/agent/linear
Connect the Mintlify agent to Linear to create documentation updates from issues, comments, and project activity.
Connect your Linear workspace to the agent to make documentation updates from Linear. When you mention the Mintlify agent in a Linear comment or assign it to an issue, the agent builds context from the issue and opens a pull request with proposed changes to your documentation.
## Connect your Linear workspace
1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Linear app**.
3. Follow the Linear prompts to authorize the Mintlify app in your workspace.
## Use the agent in Linear
Once connected, mention `@mintlify` in a Linear issue or assign an issue to `Mintlify` to trigger a documentation update. The agent uses the issue's title, description, and comment thread for context, then opens a pull request in your documentation repository.
Use the agent in Linear to:
* **Update docs from feature issues**: When a feature ships, mention the agent in the issue to draft or update the relevant documentation.
* **Act on documentation feedback**: Create Linear issues for documentation improvements and mention the agent to make the changes.
* **Generate release notes**: Mention the agent in a release-related issue to draft changelog entries based on the issue details.
* **Fix reported problems**: When someone reports a docs issue in Linear, mention the agent to resolve it.
## Best practices
* **Include context in the issue**: The more context you provide in an issue, the better the resulting pull request.
* **Review pull requests**: Always review the pull requests that the agent creates before merging them.
* **Iterate in comments**: Reply in the same issue thread to refine the agent's output, similar to how you would in Slack.
# Connect Notion to the agent
Source: https://www.mintlify.com/docs/agent/notion
Connect Notion to the Mintlify agent so it can reference your workspace pages and databases as context when creating documentation updates.
Connect your Notion workspace to the agent so that it can search your Notion content and use it as context when creating documentation updates. The additional context from your team's knowledge base, product specs, and internal documentation stored in Notion helps the agent create more accurate and complete documentation.
## Connect your Notion workspace
1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Notion app**.
3. Follow the prompts to authorize Mintlify to access your Notion workspace.
4. In Notion's authorization screen, select which pages and databases to share with Mintlify.
## What the agent can do with Notion
The Notion integration uses Notion's [MCP tools](https://developers.notion.com/guides/mcp/mcp-supported-tools#mcp-tools) to search and read your workspace content.
Your content in Notion becomes additional context for the agent to use when generating documentation.
When the agent has access to your Notion workspace, it can:
* **Search Notion**: Find relevant pages and databases in your connected Notion workspace based on the context of your request.
* **Read Notion pages**: Access the content of Notion pages to use as reference material when generating documentation.
* **Reference databases**: Pull structured data from Notion databases to inform documentation updates.
## Use cases
* **Sync product specs to docs**: Reference product requirement documents and design specs stored in Notion when writing feature documentation.
* **Document from meeting notes**: Point the agent to meeting notes or decision logs in Notion to draft documentation based on team discussions.
* **Pull from internal knowledge bases**: Use internal wikis and knowledge bases in Notion as source material for public-facing documentation.
## Best practices
* **Scope access carefully**: Only grant access to the Notion pages and databases that contain information relevant to your documentation.
* **Provide specific references**: When prompting the agent, mention the specific Notion page or database you want it to reference for best results.
* **Review generated content**: Always review pull requests to ensure information from Notion is appropriately adapted for your public documentation.
# Add the agent to Slack
Source: https://www.mintlify.com/docs/agent/slack
Add the Mintlify agent to Slack to create documentation updates from conversations, capture team knowledge, and keep docs in sync.
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.
## Connect your Slack workspace
1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Slack app**.
3. Follow the Slack prompts to install the `mintlify` app in your workspace.
4. Follow the Slack prompts to link your Mintlify account to your Slack workspace.
5. Test that the agent is working and responds when you:
* Send a direct message to the agent.
* Mention the agent with `@mintlify` in a channel.
## Use the agent in Slack
Once connected, you can:
* Send direct messages to the agent to use it privately to update your documentation.
* Mention `@mintlify` in a channel to use it publicly and collaboratively.
* Attach files and images directly to your messages for the agent to process and include in your docs.
* Continue conversations in threads to iterate on changes.
* Share pull request links with the agent to update related documentation.
## Update documentation
Use the agent to update your documentation with a new request or in an existing thread.
* **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update.
* **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update.
* **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation.
The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates.
## Track progress in real time
While the agent works on your request, it provides live feedback in the Slack thread.
* **Status updates**: A live-updating message shows what the agent is doing, such as how many files it has searched, read, and edited.
* **Task progress**: When the agent breaks your request into multiple tasks, it displays a checklist so you can track progress on each one.
* **Questions**: If the agent needs more information, it presents options for you to select from or reply in the thread with a custom answer.
* **Interruptions**: If you send a follow-up message while the agent is still working, it stops the current task and starts on the new one.
* **Completion**: When the agent finishes, it posts a summary with a link to the pull request and a link to open the changes in the web editor.
## Best practices
* **Be specific**: Tell the agent exactly what you want documented and where it should go.
* **Add context**: If a thread doesn't contain all the necessary information, include additional details in your message to the agent.
* **Review carefully**: You should always review pull requests that the agent creates before merging them.
# Use cases
Source: https://www.mintlify.com/docs/agent/use-cases
Explore real-world examples of using the Mintlify agent to automate documentation updates, capture knowledge, and maintain accurate docs.
The agent assists with many different documentation tasks. These examples show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs.
## Iterate on a prompt in a Slack thread
Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates.
For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations.
## Start with the agent, finish manually
Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task.
For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
## Update docs when merging feature changes
When you merge a feature pull request, share the PR link with the agent to update relevant docs.
For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
## Generate release notes from a pull request
Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
For example: `@mintlify Generate release notes for this PR: [PR link]`.
## Address pull request review feedback
Share a pull request link with the agent to address reviewer comments and code review feedback on documentation pull requests.
For example: `@mintlify Address the review comments on this PR: [PR link]`.
## Generate code examples
Prompt the agent to generate code examples for features throughout your docs or on specific pages.
For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
## Add images or files to your docs
Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation.
For example: `@mintlify Add this diagram to the architecture overview page` with the image attached to the message.
## Review existing content
Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues.
For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
## Respond to user feedback
Prompt the agent with feedback from your users to make focused updates to your docs.
For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
## Automate with workflows
Create workflows to automate recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product.
See [Workflows](/agent/workflows) for more information.
## Automate with the API
Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.
Use the agent endpoints to [create jobs](/api/agent/v2/create-agent-job), [get job status](/api/agent/v2/get-agent-job), and [send messages](/api/agent/v2/send-message).
When creating jobs via the API, you can control whether pull requests open in draft mode using the `asDraft` parameter (defaults to `false`). Set `asDraft: true` to create draft pull requests, or keep the default to create non-draft pull requests ready for immediate review and merging in automated workflows.
Learn how to set up API automation in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.
# Workflows
Source: https://www.mintlify.com/docs/agent/workflows
Set up automated documentation workflows with scheduled or event-triggered agent tasks, including cron schedules and webhook-based automation.
Workflows are in beta. They're currently free for all plans during the beta period. Workflow features, availability, and pricing are subject to change.
Workflows run the agent automatically on a schedule or on a push to a repository. Each workflow defines a prompt for the agent and a trigger for when to run it.
When a workflow runs, the agent clones any specified repositories as context, follows the prompt, and either opens a pull request or pushes changes directly to your deployment branch.
Each workflow can run up to 50 times a day. Runs that fail do not count toward this limit.
Use workflows that run on a schedule to automate recurring tasks like publishing changelogs or checking for grammar and style issues.
Use workflows that run on push events to automate reactive maintenance tasks like updating API references or identifying documentation updates needed for new features.
## Create a workflow
### Create a workflow in the dashboard
1. Open the [Workflows](https://dashboard.mintlify.com/products/workflows) page.
2. Click **New workflow**.
3. Configure the workflow name, trigger type, repositories, and schedule.
4. Write the agent instructions and choose whether to auto-merge pull requests.
5. Optionally, enable Slack notifications for when the workflow completes.
6. Click **Create workflow**.
### Create a workflow file with the CLI
If you have the [Mintlify CLI](/cli) installed, run the following command from your documentation repository to create a workflow file interactively in the CLI.
```bash theme={null}
mint workflow
```
The CLI prompts you for information about the workflow and creates a `.md` file in the `.mintlify/workflows/` directory. Commit and push the file to activate the workflow.
If you run `mint workflow` in a non-interactive environment such as a CI/CD pipeline or an AI coding agent, the CLI returns usage instructions and the workflow file format instead of interactive prompts.
### Add a workflow file to your repository
Create a `.md` file for each workflow in a `.mintlify/workflows/` directory at the root of your documentation repository. Each file defines one workflow.
If you have a monorepo, place the `.mintlify/workflows/` folder inside your documentation root directory where your `docs.json` file is, not at the repository root.
Workflow files use YAML frontmatter to configure the workflow, followed by a Markdown prompt for the agent.
```markdown .mintlify/workflows/update-changelog.md theme={null}
---
name: Update changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
---
Review all changes since the last changelog update. Draft a new changelog post with any new features, bug fixes, or breaking changes.
Include information about what changed and how it affects users.
Do not include any internal-only information or minor changes like bumping package versions or updating documentation.
Success criteria: Someone who reads the changelog knows the most up to date information about the product including what changed and whether or not it affects them.
```
## Frontmatter fields
| Field | Required | Description |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name` | Yes | Display name shown in the dashboard. |
| `on` | Yes | Trigger configuration. |
| `context` | No | Repositories cloned as reference when the workflow runs. |
| `automerge` | No | Defaults to `false`, which opens a pull request for review. If `true`, opens a pull request and automatically merges it. |
| `notify` | No | Notification configuration. Send Slack messages when workflows complete. |
You must have the Mintlify GitHub App installed on every repository listed in the `context` or `on.push.repo` fields. Add new repositories on the [GitHub app](https://dashboard.mintlify.com/settings/organization/github-app) page of your Mintlify dashboard.
### Triggers
Each workflow must define exactly one trigger using the `on` field.
#### On schedule (cron)
Run a workflow on a recurring schedule using a cron expression. All schedules run in UTC.
Workflows queue within 10 minutes of the scheduled time and may take up to 10 minutes to run.
```yaml theme={null}
on:
cron: "0 9 * * 1"
```
The value is a standard 5-field cron expression in `minute hour day-of-month month day-of-week` format. Use a tool like [crontab.guru](https://crontab.guru) to build and validate schedules.
| Expression | Schedule |
| --------------- | --------------------------------------- |
| `"0 9 * * 1"` | Every Monday at 9:00 AM UTC |
| `"0 0 1 * *"` | First day of each month at midnight UTC |
| `"0 8 * * 1-5"` | Weekdays at 8:00 AM UTC |
#### On push events
Run a workflow when changes push to a specific repository or branch. This includes both pull request merges and direct pushes to the branch.
```yaml theme={null}
on:
push:
- repo: your-org/your-product
branch: main
```
* `repo`: The GitHub repository in `owner/repo` format.
* `branch` (optional): The branch to watch for pushes. If you don't specify a branch, the workflow triggers on pushes to the repository's default branch.
A workflow can watch for pushes to multiple repositories or branches.
```yaml theme={null}
on:
push:
- repo: your-org/your-product
- repo: your-org/another-repo
branch: release
```
### Context repositories
Use `context` to give the agent read access to additional repositories when the workflow runs. This is useful when your prompt requires reviewing code or content outside your documentation repository. You can specify up to five context repositories per workflow.
```yaml theme={null}
context:
- repo: your-org/your-product
- repo: your-org/design-system
```
### Auto-merge changes
By default, the agent opens a pull request for each workflow run so you can review changes before they go live. Set `automerge: true` to automatically merge the pull request without requiring manual approval. This gives you a record of changes in your repository's pull request history while automating the merge step.
Automerge requires the Mintlify GitHub App to have bypass permissions on all rulesets that target your deploy branch, including organization-level and repository-level rulesets. See [Configure automerge](/guides/configure-automerge) for setup instructions.
```yaml theme={null}
automerge: true
```
### Slack notifications
Send Slack messages when a workflow completes or fails. Notifications include the workflow status, a link to the pull request, and a summary of the changes.
Slack notifications require the Mintlify Slack app in your organization's Slack workspace. Install the Slack app from your [dashboard](https://dashboard.mintlify.com/products/agent).
#### Configure Slack notifications in the dashboard
When creating or editing a workflow in the dashboard, you can enable Slack notifications under the **Notify on completion** toggle:
1. If you haven't connected Slack, click **Install Slack app**.
2. Click the **Notify on completion** toggle.
3. Search for and select the channels you want to notify.
4. Save your workflow.
#### Configure Slack notifications in workflow files
Use the `notify` field to configure Slack notifications in a workflow file:
```yaml theme={null}
notify:
slack:
channels:
- documentation
- dev-updates
users:
- alice
- bob
```
You can specify notification targets by name or by ID:
| Field | Description |
| ------------- | ----------------------------------------------------- |
| `channels` | Channel names to notify (with or without `#` prefix). |
| `channel_ids` | Channel IDs to notify. |
| `users` | Usernames, display names, or real names to DM. |
| `user_ids` | Slack user IDs to DM. |
## Manage workflows
If you create a workflow in the dashboard, edit or delete it from the dashboard.
If you create a workflow from a file in your repository, edit or delete it with a pull request modifying the file.
### Trigger a workflow manually
You can run cron-based workflows on demand without waiting for the next scheduled time. Manually triggered runs count toward the daily run limit.
1. Go to the [Workflows](https://dashboard.mintlify.com/products/workflows) page in your dashboard.
2. Click **View Workflows**.
3. Click the settings button for the workflow you want to run.
4. Click the manually trigger workflow button to trigger the workflow.
### Disable a workflow
Disable a workflow to temporarily stop it from running without deleting it. Disabled workflows keep their configuration and run history, but do not execute on their schedule or in response to push events. You cannot manually trigger a disabled workflow.
To toggle a workflow:
1. Go to the [Workflows](https://dashboard.mintlify.com/products/workflows) page in your dashboard.
2. Click **View Workflows**.
3. Click the toggle next to the workflow you want to disable or enable.
When you re-enable a cron-based workflow, its next run time is recalculated from the current time.
## Prompts
Effective prompts focus on one task and have a specific outcome in mind. Workflows always have some variance because of the nondeterministic nature of agents, but you can improve the consistency of workflow outputs by following these best practices.
* Describe the outcome you want the agent to achieve.
* Include success criteria.
* Specify the context you want the agent to use.
* Split complex tasks into steps or multiple workflows.
### Agent environment
The agent runs in an isolated sandbox with restricted internet access. When writing prompts, only reference tools available to the agent.
* Standard shell utilities (`grep`, `sed`, `awk`, `curl`, and others)
* `git` and the GitHub CLI (`gh`)
* The Mintlify CLI (`mint`)
* Node.js and Bun
The agent cannot install additional packages or tools at runtime. Package registries and other external services are not reachable from the sandbox.
Prompts that instruct the agent to run unavailable tools may produce unexpected results or fail.
## Example workflows
### Draft documentation for new features
If you use agent suggestions in your dashboard, this workflow replicates that behavior.
Add this workflow with any modifications for your project to automatically draft documentation as you add new features to your product.
Runs when you push changes to your product repository to identify documentation updates needed for any new features or APIs.
```markdown .mintlify/workflows/draft-feature-docs.md theme={null}
---
name: Draft docs for new features
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
Review the diff from the last merged PR in `your-org/your-product`. Identify any new features, APIs, or other changes that require documentation.
For each new addition, draft documentation updates that explain what it does, when to use it, and how to configure it. Include a code example where relevant.
Success criteria: After reading any new or updated documentation, users understand what the feature is, if it applies to tasks they do, and how to use it.
## Important
- Only document changes that affect end users. Skip internal refactors or dependency updates.
- Match the style and structure of existing docs pages.
```
### Style audit
Runs when changes push to your documentation repository to catch style guide violations before they accumulate. This example workflow automatically fixes style guide violations and lists any violations that require human judgment in the PR body.
```markdown .mintlify/workflows/style-audit.md theme={null}
---
name: Style audit
on:
push:
- repo: your-org/your-docs
branch: main
automerge: false
---
Review all MDX files changed in the last merged PR against the style guide at `path/to/style-guide`.
Open a pull request to resolve any style violations that can be fixed automatically. For any edits that require judgment or nuance, note them in the PR body with the specific lines, rule violations, and suggested fixes.
Success criteria:
- All style violations have a proposed resolution.
- No new style violations are introduced.
## Important
- Do not change content meaning. Only correct style violations.
- Skip any files in language subdirectories (`es/`, `fr/`, `zh/`).
```
### Update API reference
Runs when pull requests merge to your product repository to keep API reference pages in sync with your product code. When endpoints or parameters change, this workflow updates the corresponding content in your documentation.
```markdown .mintlify/workflows/update-api-reference.md theme={null}
---
name: Update API reference
on:
push:
- repo: your-org/your-product
branch: main
context:
- repo: your-org/your-docs
automerge: false
---
Review the diff from the last merged PR in `your-org/your-product` for changes to API endpoints, parameters, response shapes, or error codes.
Update the corresponding API specifications or pages in the docs to reflect the changes. Include updated parameter descriptions, type information, and examples where affected.
Success criteria: All API specifications and pages are up to date with the changes in the product repository.
## Important
- If a parameter or endpoint was removed, mark it as deprecated rather than deleting it unless the code explicitly removes it with no deprecation period.
- If no API changes were introduced, do nothing.
```
### Track translation lag
Run weekly to compare English source files against their translations and identify pages that have fallen behind.
To use this workflow, update the example language subdirectories (`es/`, `fr/`, `zh/`) to your actual language subdirectories.
```markdown .mintlify/workflows/translation-lag.md theme={null}
---
name: Track translation lag
on:
cron: "0 9 * * 3"
---
Compare the English MDX files in the repo against their counterparts in the `es/`, `fr/`, and `zh/` subdirectories. Use git history to identify English files updated more recently than their translations.
Open a pull request that lists pages that are out of sync, organized by language. For each page, include the date of the last English update and a brief summary of what changed so translators have context on what to update.
Success criteria: Any discrepancies between the English and translated files are identified and listed in the pull request.
## Important
- If a translated file does not exist, flag it as missing rather than out of sync.
- Group findings by language, then by how far out of date they are (most stale first).
```
### SEO and metadata audit
Runs weekly to check for pages with missing or weak metadata and open a pull request with improvements. This example workflow checks for missing, weak, or duplicate `title` and `description` frontmatter and flags boilerplate patterns. Edit the workflow to check for other metadata or content issues that you prioritize for your documentation.
```markdown .mintlify/workflows/seo-audit.md theme={null}
---
name: SEO and metadata audit
on:
cron: "0 9 * * 1"
automerge: false
---
Audit all MDX files in the docs for SEO and metadata quality. Check for:
- Missing or empty `title` frontmatter
- Titles that are too long (over 60 characters) — long titles are truncated in search result snippets
- Titles that follow a boilerplate pattern like "PageType - Name" without describing the specific content of the page
- Missing or empty `description` frontmatter
- Descriptions that are too short (under 130 characters) — short descriptions are frequently ignored by Google in favor of auto-generated snippets
- Descriptions that are too long (over 160 characters)
- Pages that share an identical description with other pages — each page needs a unique description
Open a pull request with improvements for any issues found.
When writing titles: be descriptive and specific about what the page covers. Avoid generic patterns like "Overview - Product Name". Target 50-60 characters.
When writing descriptions: summarize what the specific page covers in plain language. Include 2-3 terms a user would actually search for. Never reuse the same description across pages. Target 130-155 characters.
Success criteria: All pages have a unique title under 60 characters that describes the specific content, and a unique description between 130 and 160 characters.
## Important
- Only update frontmatter. Do not change page content.
- If all pages have complete and reasonable metadata, do nothing.
```
### Changelog with notifications
Runs weekly to generate a changelog and notify your team on Slack when the workflow completes. This example shows how to combine scheduled workflows with Slack notifications.
```markdown .mintlify/workflows/changelog-with-notify.md theme={null}
---
name: Weekly changelog
on:
cron: "0 9 * * 1"
context:
- repo: your-org/your-product
automerge: false
notify:
slack:
channels:
- documentation
users:
- tech-writer
---
Review all merged PRs in `your-org/your-product` from the past week. Draft a changelog entry summarizing new features, bug fixes, and breaking changes.
Success criteria: The changelog accurately reflects the week's changes and is ready for review.
```
# AI-native documentation
Source: https://www.mintlify.com/docs/ai-native
Discover how AI-native features enhance reading, writing, and discovering your documentation with the assistant, agent, and MCP server.
When you host your documentation on Mintlify, built-in AI features help your users find answers and your team maintain content more efficiently. Your content provides the context for these AI-native features to improve the experiences of reading, writing, and discovering your documentation.
## What makes your documentation AI-native
### Reading
In addition to reading individual pages, users can chat with the [assistant](/ai/assistant) in your documentation for immediate answers to their questions and links to relevant content. The assistant helps guide users through your product with accurate information from your documentation. Embed the assistant into custom apps with the [API](/api/assistant/create-assistant-message-v2) to extend where users can access your documentation.
### Writing
The [agent](/agent) helps you write and maintain documentation. It creates pull requests with proposed changes based on your prompts, pull requests, and Slack threads. Add the agent to your Slack workspace so that anyone on your team can help maintain your documentation by chatting with the agent. Or embed the agent into custom apps via the [API](/api/agent/v2/create-agent-job).
Create [workflows](/agent/workflows) to run the agent on a schedule or on a push to a repository. Each workflow defines a prompt for the agent and a trigger for when to run it.
Configure popular tools like [Cursor](/guides/cursor), [Claude Code](/guides/claude-code), and [Windsurf](/guides/windsurf) to reference the Mintlify schema, your style guide, and best practices.
### Discovering
Your site is automatically optimized for AI tools and search engines to help users discover your documentation. All pages send their content as Markdown to AI agents instead of HTML, which helps these tools process your content faster and use fewer tokens. Every page is also available to view as Markdown by appending `.md` to the URL.
Mintlify hosts `llms.txt` and `skill.md` files for your documentation. These industry-standard files help LLMs respond efficiently with relevant information to user queries and provide a list of capabilities for agents to use, so that users are more successful with your product.
Your documentation site also hosts an MCP server that lets users connect your documentation directly to their AI tools for up-to-date information about your product directly where they want it.
Full-text search and semantic understanding help users and AI tools find relevant information quickly. Search understands user intent rather than just matching keywords. And if a user encounters a 404 error, your site suggests related pages to help them find what they're looking for. No configuration required.
## Enable AI features
Select any of the following cards for more information.
Configure the assistant to search external sites or direct people to your support team if it can't answer their questions.
Get documentation updates automatically on a schedule or when a push event occurs.
Add a menu to pages that lets users query AI tools, connect to your MCP server, and copy pages as context with one click.
# Add SDK examples
Source: https://www.mintlify.com/docs/api-playground/adding-sdk-examples
Add SDK code samples to your API documentation with autogenerated examples from Speakeasy and Stainless across multiple languages.
If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages.
Add this property to any request method. It has the following schema.
The language of the code sample.
The label for the sample. This is useful when providing multiple examples for a single endpoint.
The source code of the sample.
Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
```yaml theme={null}
paths:
/plants:
get:
# ...
x-codeSamples:
- lang: bash
label: List all unwatered plants
source: |
planter list -u
- lang: javascript
label: List all unwatered plants
source: |
const planter = require('planter');
planter.list({ unwatered: true });
- lang: bash
label: List all potted plants
source: |
planter list -p
- lang: javascript
label: List all potted plants
source: |
const planter = require('planter');
planter.list({ potted: true });
```
# AsyncAPI setup
Source: https://www.mintlify.com/docs/api-playground/asyncapi-setup
Set up real-time WebSocket documentation using AsyncAPI specification files to generate interactive channel and message reference pages.
## Demo
See the [WebSocket playground](/api-playground/websocket-playground) for an example of the AsyncAPI playground.
## Add an AsyncAPI specification file
To create pages for your WebSocket channels, you must have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0).
Use the [AsyncAPI Studio](https://studio.asyncapi.com/) to validate your AsyncAPI schema.
```json {3} theme={null}
/your-project
|- docs.json
|- asyncapi.json
```
## Auto-populate WebSocket pages
To automatically generate pages for all channels in your AsyncAPI schema, add an `asyncapi` property to any navigation element. The `asyncapi` property accepts a path to an AsyncAPI schema document in your documentation repo, a URL to a hosted AsyncAPI document, or an array of links to AsyncAPI schema documents.
### Examples with tabs
```json Local file theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "/path/to/asyncapi.json"
}
]
}
```
```json Remote URL theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
}
]
}
```
```json Multiple files theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": [
"/path/to/events.json",
"/path/to/webhooks.json"
]
}
]
}
```
When you specify multiple AsyncAPI files, each file generates its own set of channel pages.
### Examples with groups
```json theme={null}
"navigation": {
"tabs": [
{
"tab": "AsyncAPI",
"groups": [
{
"group": "Websockets",
"asyncapi": {
"source": "/path/to/asyncapi.json",
"directory": "websockets"
}
}
]
}
]
}
```
The `directory` field is optional. If not specified, Mintlify adds the files to the **api-reference** folder of the docs repository.
## Channel page
If you want more control over how you order your channels or if you want to reference only specific channels, create an MDX file with the `asyncapi` property in the frontmatter.
```mdx theme={null}
---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---
```
# Complex data types
Source: https://www.mintlify.com/docs/api-playground/complex-data-types
Describe APIs with flexible schemas using oneOf, anyOf, and allOf keywords for optional properties, polymorphism, and multiple data formats.
When your API accepts multiple data formats, has conditional fields, or uses inheritance patterns, OpenAPI's schema composition keywords help you document these flexible structures. Using `oneOf`, `anyOf`, and `allOf`, you can describe APIs that handle different input types or combine multiple schemas into comprehensive data models.
## `oneOf`, `anyOf`, `allOf` keywords
For complex data types, OpenAPI provides keywords for combining schemas:
* `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator.
* `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator.
* `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator.
Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API.
For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
The `not` keyword is currently unsupported.
### Combining schemas with `allOf`
When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI's reusable [components](https://swagger.io/docs/specification/components/).
```yaml theme={null}
org_with_users:
allOf:
- $ref: '#/components/schemas/Org'
- type: object
properties:
users:
type: array
description: An array containing all users in the organization
# ...
components:
schemas:
Org:
type: object
properties:
id:
type: string
description: The ID of the organization
```
The ID of the organization
An array containing all users in the organization
### Providing options with `oneOf` and `anyOf`
When you use `oneOf` or `anyOf`, the options display in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses:
```yaml theme={null}
delivery_address:
oneOf:
- title: StreetAddress
type: object
properties:
address_line_1:
type: string
description: The street address of the recipient
# ...
- title: POBox
type: object
properties:
box_number:
type: string
description: The number of the PO Box
# ...
```
The street address of the residence
The number of the PO Box
# Manage page visibility
Source: https://www.mintlify.com/docs/api-playground/managing-page-visibility
Control which API endpoints appear in your documentation navigation by hiding, filtering, or organizing autogenerated OpenAPI pages.
For internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation, you can control which OpenAPI operations get published as documentation pages and their visibility in navigation.
If your pages are autogenerated from an OpenAPI document, manage page visibility with the `x-hidden` and `x-excluded` extensions.
## `x-hidden`
The `x-hidden` extension creates a page for an endpoint, but hides it from navigation. The page is only accessible by navigating directly to its URL.
Common use cases for `x-hidden` are:
* Endpoints you want to document, but not promote.
* Pages that you link to from other content.
* Endpoints for specific users.
## `x-excluded`
The `x-excluded` extension completely excludes an endpoint from your documentation.
Common use cases for `x-excluded` are:
* Internal-only endpoints.
* Deprecated endpoints that you don't want to document.
* Beta features that are not ready for public documentation.
## Implementation
Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification.
Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path.
```json Endpoint example {11, 19} theme={null}
"paths": {
"/plants": {
"get": {
"description": "Returns all plants from the store",
"parameters": { /*...*/ },
"responses": { /*...*/ }
}
},
"/hidden_plants": {
"get": {
"x-hidden": true,
"description": "Returns all somewhat secret plants from the store",
"parameters": { /*...*/ },
"responses": { /*...*/ }
}
},
"/secret_plants": {
"get": {
"x-excluded": true,
"description": "Returns all top secret plants from the store (do not publish this endpoint!)",
"parameters": { /*...*/ },
"responses": { /*...*/ }
}
}
},
```
```json Webhook example {9, 15} theme={null}
"webhooks": {
"/plants_hook": {
"post": {
"description": "Webhook for information about a new plant added to the store",
}
},
"/hidden_plants_hook": {
"post": {
"x-hidden": true,
"description": "Webhook for somewhat secret information about a new plant added to the store"
}
},
"/secret_plants_hook": {
"post": {
"x-excluded": true,
"description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
}
}
}
```
# Create manual API pages
Source: https://www.mintlify.com/docs/api-playground/mdx-setup
Create API reference pages manually with MDX files when you need full control over layout for small APIs, prototypes, or custom docs.
You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs or prototyping.
## Setup
In your `docs.json` file, define your base URL and authentication method.
```json Example docs.json theme={null}
"api": {
"mdx": {
"server": "https://api.acme.com/",
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
If you want to hide the API playground, set the `display` field to `none`. You don't need to include an authentication method if you hide the playground.
```json theme={null}
"api": {
"playground": {
"display": "none"
}
}
```
Find a full list of API configurations in [Settings](/organize/settings-api).
Create an MDX file for each endpoint. Define the `title` and `api` in the frontmatter:
```mdx theme={null}
---
title: 'Create new user'
api: 'POST /v1/users'
---
```
The `api` frontmatter field accepts either a full URL or a relative path:
* **Full URL** like `POST https://api.acme.com/v1/users`. The `server` field in `docs.json` is ignored for that endpoint.
* **Relative path** like `POST /v1/users`. Requires a `server` field in `docs.json`. The server URL is prepended to the path.
Specify path parameters by wrapping them in `{}`:
```bash theme={null}
https://api.example.com/v1/endpoint/{userId}
```
To override the global playground display mode for a specific page, add `playground` to the frontmatter:
```mdx theme={null}
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
```
Options:
* `playground: 'interactive'` - Display the interactive playground (default)
* `playground: 'simple'` - Display a copyable endpoint with no playground
* `playground: 'none'` - Hide the playground entirely
Use [parameter and response fields](/components/fields) to document your endpoint's parameters and return values.
```mdx theme={null}
Unique identifier for the user
User's email address
Unique identifier for the newly created user
User's email address
```
Add your endpoint pages to the navigation by updating the `pages` field in your `docs.json`:
```json docs.json theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users",
"pages": [
"api-reference/users/create-user",
"api-reference/users/get-user",
"api-reference/users/update-user"
]
},
{
"group": "Orders",
"pages": [
"api-reference/orders/create-order",
"api-reference/orders/list-orders"
]
}
]
}
]
}
```
Each page path corresponds to an MDX file in your docs repository. For example, `api-reference/users/create-user.mdx`. Learn more about structuring your docs in [Navigation](/organize/navigation).
### Using OpenAPI endpoints in navigation
If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files. Reference specific endpoints by including the OpenAPI file path and the endpoint:
```json docs.json theme={null}
"navigation": {
"pages": [
"introduction",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
You can also set a default OpenAPI spec for a navigation group and reference endpoints by method and path:
```json docs.json theme={null}
{
"group": "API reference",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Orders",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
For more details on OpenAPI integration, see [OpenAPI setup](/api-playground/openapi-setup).
## Enable authentication
You can set authentication globally in `docs.json` or override it on individual pages using the `authMethod` field in frontmatter. A page-specific method overrides the global setting.
### Bearer token
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "bearer"
---
```
### Basic authentication
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "basic"
---
```
### API key
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "key"
---
```
### None
To disable authentication on a specific page, set `authMethod` to `none`:
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "none"
---
```
# Multiple responses
Source: https://www.mintlify.com/docs/api-playground/multiple-responses
Document multiple response variations for API endpoints, including success and error cases, with status codes and example payloads.
If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the `examples` property.
Add this property to any response. It has the following schema.
```yaml theme={null}
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/YourResponseSchema"
examples:
us:
summary: Response for United States
value:
countryCode: "US"
currencyCode: "USD"
taxRate: 0.0825
gb:
summary: Response for United Kingdom
value:
countryCode: "GB"
currencyCode: "GBP"
taxRate: 0.20
```
The playground also handles non-JSON response types differently based on their content type.
## Audio response examples
For endpoints that return audio files, set the response content type to `audio/*` and provide a URL to an audio file as the example value. The playground renders an interactive audio player instead of a code snippet.
```yaml theme={null}
responses:
"200":
description: Audio file generated successfully
content:
audio/mpeg:
schema:
type: string
format: binary
examples:
sample:
summary: Sample audio output
value: "https://example.com/sample-audio.mp3"
```
# OpenAPI setup
Source: https://www.mintlify.com/docs/api-playground/openapi-setup
Generate interactive API documentation from OpenAPI specification files with automatic endpoint pages, request builders, and navigation.
OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.
## Add an OpenAPI specification file
To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0 or 3.1](https://swagger.io/specification/).
Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Specifications stored in your repository are [served as downloadable files](/create/files) at their path on your docs domain. For example, `https://your-domain/docs/openapi.json`.
Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.
```json Single specification theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
```
```json Multiple specifications theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"openapi/v1.json",
"openapi/v2.json"
]
}
]
}
```
Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. External references are not supported.
### Describe your API
We recommend the following resources to learn about and construct your OpenAPI specification.
* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
* [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
* [Swagger Editor](https://editor.swagger.io/) to edit, validate, and debug your OpenAPI document.
* [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint validate`.
Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog.
### Specify the base URL for your API
To enable the API playground, add a `servers` field to your OpenAPI specification with your API's base URL.
```json theme={null}
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
In an OpenAPI specification, different API endpoints are specified by their paths, like `/users/{id}` or simply `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation.
The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown allows users to toggle between servers. If you do not specify a server, the API playground uses simple mode since it cannot send requests without a base URL.
If your API has endpoints that exist at different URLs, you can [override the `servers` field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.
### Specify authentication
To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI specification. The API descriptions and API playground add authentication fields based on the security configurations in your OpenAPI specification.
Add a `securitySchemes` field to define how users authenticate.
This example shows a configuration for bearer authentication.
```json theme={null}
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Add a `security` field to require authentication.
```json theme={null}
{
"security": [
{
"bearerAuth": []
}
]
}
```
Common authentication types include:
* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens.
* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password.
If different endpoints within your API require different methods of authentication, you can [override the `security` field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation.
For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation.
#### Set default values for security schemes
Use the `x-default` extension on a security scheme to pre-fill the authentication field in the API playground. This is useful for providing placeholder values or test credentials that help users get started quickly.
```json {6} theme={null}
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "your-api-key-here"
}
}
}
}
```
The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields.
You can also use `x-default` on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition.
## Customize your endpoint pages
Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension gives you additional control over how your API documentation generates and displays.
### Metadata
Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in MDX frontmatter except for `openapi`.
```json {7-13} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Get users",
"description": "Retrieve a list of users",
"x-mint": {
"metadata": {
"title": "List all users",
"description": "Fetch paginated user data with filtering options",
"og:title": "Display a list of users"
}
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
You can also control playground display per endpoint using the `playground` and `groups` metadata fields:
```json {7-11} theme={null}
{
"paths": {
"/admin/users": {
"post": {
"summary": "Create admin user",
"x-mint": {
"metadata": {
"playground": "auth",
"groups": ["admin"],
"public": true
}
}
}
}
}
}
```
This configuration makes the page publicly visible while restricting the interactive playground to authenticated users in the `admin` group.
### Content
Add content before the auto-generated API documentation using `x-mint: content`. The `x-mint: content` extension supports all Mintlify MDX components and formatting.
```json {6-8} theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Create user",
"x-mint": {
"content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\nUser emails must be unique across the system."
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
### href
Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.
```json {6-8, 14-16} theme={null}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Legacy endpoint",
"x-mint": {
"href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
"/documented-elsewhere": {
"post": {
"summary": "Special endpoint",
"x-mint": {
"href": "/guides/special-endpoint-guide"
}
}
}
}
}
```
## Auto-populate API pages
Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
The `openapi` field accepts either a path in your docs repo or a URL to a hosted OpenAPI document.
When you use a URL for your OpenAPI spec, changes to the spec don't trigger a Git push, so your docs won't redeploy automatically. To keep your docs in sync, call the [Trigger deployment](/api/update/trigger) API endpoint in the same CI action that generates or updates your spec. This way your docs update automatically without needing to manually trigger a deployment from the dashboard.
Generated endpoint pages have these default metadata values:
* `title`: The operation's `summary` field, if present. If there is no `summary`, Mintlify generates the title from the HTTP method and endpoint.
* `description`: The operation's `description` field, if present.
* `version`: The `version` value from the parent anchor or tab, if present.
* `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.
To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/api-playground/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec.
There are two approaches for adding endpoint pages into your documentation:
1. **Dedicated API sections**: Reference OpenAPI specs in navigation elements for dedicated API sections.
2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages.
### Dedicated API sections
Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification appear in the generated section.
```json {5} theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification.
```json {8-11, 15-18} theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users API",
"openapi": {
"source": "/path/to/users-openapi.json",
"directory": "users-api-reference"
}
},
{
"group": "Admin API",
"openapi": {
"source": "/path/to/admin-openapi.json",
"directory": "admin-api-reference"
}
}
]
}
]
}
```
The `directory` field is optional and specifies where Mintlify stores generated API pages in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.
### Selective endpoints
When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.
#### Set a default OpenAPI spec
Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field.
```json {12, 15-16} theme={null}
"navigation": {
"tabs": [
{
"tab": "Getting started",
"pages": [
"quickstart",
"installation"
]
},
{
"tab": "API reference",
"openapi": "/path/to/openapi.json",
"pages": [
"api-overview",
"GET /users",
"POST /users",
"guides/authentication"
]
}
]
}
```
Any page entry matching the format `METHOD /path` generates an API page for that endpoint using the default OpenAPI specification.
#### OpenAPI spec inheritance
Child navigation elements inherit their parent's OpenAPI specification unless they define their own.
```json {3, 7-8, 11, 13-14} theme={null}
{
"group": "API reference",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Orders",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
#### Individual endpoints
Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.
```json {5-6} theme={null}
"navigation": {
"pages": [
"introduction",
"user-guides",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
This approach is useful when you need individual endpoints from different specifications, only want to include select endpoints, or want to include endpoints alongside other types of documentation.
## Create MDX pages from your OpenAPI specification
For more granular control over individual endpoint pages, create MDX pages from your OpenAPI specification. This lets you customize page metadata, content, and reorder or exclude pages in your navigation while still using the auto-generated parameters and responses.
There are two ways to document your OpenAPI specification with individual MDX pages:
* Document endpoints with the `openapi` field in the frontmatter.
* Document data models with the `openapi-schema` field in the frontmatter.
### Document endpoints
Create a page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter.
```mdx Example theme={null}
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
```mdx Format theme={null}
---
title: "title of the page"
description: "description of the page"
openapi: openapi-file-path method path
deprecated: boolean (not required)
version: "version-string" (not required)
---
```
The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`.
#### Autogenerate endpoint pages
To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).
```bash theme={null}
npx @mintlify/scraping@latest openapi-file -o
```
Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files populate in the working directory.
### Document data models
Create a page for each data structure defined in your OpenAPI specification's `components.schemas` using the `openapi-schema` field in the frontmatter.
```mdx Example theme={null}
---
openapi-schema: OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "openapi-file-path schema-key"
---
```
If you have schemas with the same name in multiple files, specify the OpenAPI file:
```mdx Example theme={null}
---
openapi-schema: en-schema.json OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "path-to-schema-file schema-key"
---
```
## Webhooks
Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1+ documents support webhooks.
Add a `webhooks` field to your OpenAPI document alongside the `paths` field.
For more information on defining webhooks, see [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) in the OpenAPI documentation.
To create an MDX page for a webhook (OpenAPI 3.1+), use `webhook` instead of an HTTP method:
```mdx theme={null}
---
title: "Order updated webhook"
description: "Triggered when an order is updated"
openapi: "openapi.json webhook orderUpdated"
---
```
The webhook name must exactly match the key in your OpenAPI spec's `webhooks` field.
# Playground
Source: https://www.mintlify.com/docs/api-playground/overview
Let developers test API endpoints directly in your documentation with an interactive playground that sends real requests and shows responses.
The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation.
See [Trigger an update](/api/update/trigger) for an example of the API playground in action.
The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages.
We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
## Get started
Validate your OpenAPI specification file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint) command `mint validate`.
```bash {3} theme={null}
/your-project
|- docs.json
|- openapi.json
```
Update your `docs.json` to reference your OpenAPI specification.
**To automatically generate pages for all endpoints in your OpenAPI specification**, add an `openapi` property to any navigation element.
This example generates a page for each endpoint specified in `openapi.json` and organizes the pages in the "API reference" group.
```json Generate all endpoint pages theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json"
}
]
}
```
**To generate pages for only specific endpoints**, list the endpoints in the `pages` property of the navigation element.
This example generates pages for only the `GET /users` and `POST /users` endpoints. To generate other endpoint pages, add additional endpoints to the `pages` array.
```json Generate specific endpoint pages theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
```
## Customize your playground
Customize your API playground by defining the following properties in your `docs.json`.
Configurations for the API playground.
The display mode of the API playground.
* `"interactive"`: Display the interactive playground.
* `"simple"`: Display a copyable endpoint with no playground.
* `"none"`: Display nothing.
* `"auth"`: Display the interactive playground only to authenticated users. Unauthenticated users or users not in the required groups see no playground.
Defaults to `interactive`.
Whether to pass API requests through Mintlify's proxy server. Defaults to `true`.
When `true`, playground requests are routed through Mintlify's servers. When `false`, the playground sends requests directly from the browser to your API. Set to `false` when your API accepts direct browser requests and you don't need Mintlify to proxy the traffic. For example, when your API requires specific headers that can't be forwarded through the proxy or when you need the request to originate directly from the user's browser for authentication purposes.
Whether to include cookies, authorization headers, and TLS client certificates for cross-origin requests when `proxy` is `false`. Defaults to `false`.
When `true` and `proxy` is `false`, the playground sends requests with browser-managed credentials included. For example, when your API uses cookie-based authentication or HTTP session tokens.
This option has no effect when `proxy` is `true`.
The display mode for base URLs in endpoint headers. When set to `full`, the full base URL displays for every endpoint page. By default, only the relative endpoint path displays.
Configurations for the autogenerated API examples.
Example languages for the autogenerated API snippets.
Languages display in the order specified.
| Display name | Key | Aliases |
| ------------ | ------------ | ------------------------- |
| cURL | `bash` | `curl`, `sh`, `shell` |
| Python | `python` | `py` |
| JavaScript | `javascript` | `js` |
| Node.js | `node` | `nodejs`, `node.js` |
| PHP | `php` | |
| Go | `go` | `golang` |
| Java | `java` | |
| Ruby | `ruby` | `rb` |
| PowerShell | `powershell` | |
| Swift | `swift` | |
| C# | `csharp` | `c#` |
| .NET | `dotnet` | `.net`, `.NET`, `dot-net` |
| TypeScript | `typescript` | `ts` |
| C | `c` | |
| C++ | `c++` | `cpp` |
| Kotlin | `kotlin` | `kt` |
| Rust | `rust` | `rs` |
| Dart | `dart` | `flutter` |
Whether to show optional parameters in API examples. Defaults to `all`.
Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
Whether to generate code samples for endpoints from API specifications. Defaults to `true`. When set to `false`, only manually written code samples (from `x-codeSamples` in OpenAPI specifications or `` components in MDX) appear in the API playground.
### Example configuration
This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. It only shows required parameters in the code snippets, and the playground prefills the request body with example values.
```json theme={null}
{
"api": {
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["curl", "python", "javascript"],
"defaults": "required",
"prefill": true
}
}
}
```
### Auth-based playground display
Use the `auth` display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users.
When `display` is set to `auth`:
* Authenticated users see the interactive playground.
* Unauthenticated users see no playground (equivalent to `none`).
You can also combine `auth` with the `groups` property in page frontmatter to restrict playground access to specific user groups.
```mdx Page with group-restricted playground theme={null}
---
title: "Create user"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
```
In this example:
* The page is publicly visible (anyone can view the documentation).
* Only authenticated users in the `admin` or `developer` groups see the interactive playground.
* Users not in those groups see no playground.
If the page has no `groups` property, all authenticated users see the interactive playground.
The `auth` display mode requires your documentation to have [authentication](/deploy/authentication-setup) configured.
### Custom endpoint pages
When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual MDX pages for your endpoints.
Both options allow you to:
* Customize page metadata
* Add additional content like examples
* Control playground behavior per page
We recommend the `x-mint` extension so that all of your API documentation generates automatically from your OpenAPI specification and stays maintained in one file.
We recommend individual MDX pages for small APIs or when you want to experiment with changes on a per-page basis.
## Response rendering
The playground automatically renders responses based on the `Content-Type` header returned by your API.
* **Images**: Rendered inline (`image/*`).
* **Audio**: Rendered with a built-in audio player (`audio/*`).
* **Video**: Rendered with a built-in video player (`video/*`). Any response with a `video/*` content type, such as `video/mp4` or `video/webm`, displays as a playable video directly in the playground.
* **All other responses**: Displayed in a code block.
## Parameter anchor links
Every parameter in the API playground has a clickable anchor link. Hover over a parameter name to reveal the link icon, then click to copy a direct URL to that parameter.
Use parameter anchor links to:
* Share links to specific parameters in support conversations or documentation
* Navigate directly to a parameter from another page or external resource
* Bookmark frequently referenced parameters
The URL format is `your-docs-url/endpoint-path#parameter-name`. For nested parameters, the anchor includes the parent path.
## Further reading
* [OpenAPI setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.
* [x-mint extension](/api-playground/openapi-setup#customize-your-endpoint-pages) for more information on customizing your endpoint pages.
* [MDX setup](/api-playground/mdx-setup) for more information on manually creating individual API reference pages.
* [AsyncAPI setup](/api-playground/asyncapi-setup) for more information on creating your AsyncAPI schema to generate WebSocket reference pages.
# Troubleshooting
Source: https://www.mintlify.com/docs/api-playground/troubleshooting
Troubleshoot common issues with API playground configuration, including OpenAPI validation errors, missing endpoints, and auth problems.
If your API pages aren't displaying correctly, check these common configuration issues.
In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
or your OpenAPI document is invalid.
Running `mint dev` locally should reveal some of these issues.
To verify your OpenAPI document passes validation:
1. Visit [this validator](https://editor.swagger.io/)
2. Switch to the "Validate text" tab
3. Paste in your OpenAPI document
4. Click "Validate it!"
If the text box that appears below has a green border, your document has passed validation.
This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document
passes validation here, there's a great chance the problem is elsewhere.
Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification,
you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3):
This is usually caused by a misspelled `openapi` field in the page metadata. Make sure
the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.
Here's an example of how things might go wrong:
```mdx get-user.mdx theme={null}
---
openapi: "GET /users/{id}/"
---
```
```yaml openapi.yaml theme={null}
paths:
"/users/{id}":
get: ...
```
Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
document does not.
Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document
in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI
documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this:
```mdx api-reference/v1/users/get-user.mdx theme={null}
---
openapi: "v1 GET /users/{id}"
---
```
If you have a custom domain configured, this could be an issue with your reverse proxy. By
default, requests made via the API Playground start with a `POST` request to the
`/_mintlify/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET`
requests, then all of these requests fail. To fix this, configure your reverse proxy to
allow `POST` requests to the `/_mintlify/api/request` path.
Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described in the [settings documentation](/organize/settings-api). When using this configuration, you must configure CORS on your server since requests come directly from users' browsers rather than through your proxy.
If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set for the navigation element:
```json {5} theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "/path/to/openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
```
2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
3. **Validation issues**: Use `mint validate` to verify your OpenAPI document is valid.
1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations appear in navigation. No other pages are automatically added. This includes operations that are referenced in child navigation elements.
When combining OpenAPI operations with regular documentation pages in navigation:
1. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation. If you need to have a file that shares a name with an operation, use the `x-mint` extension for the endpoint to have the href point to a different location.
2. **Path resolution**: Navigation entries that don't match OpenAPI operations are treated as file paths. Ensure your `MDX` files exist at the expected locations.
3. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
# Analyze your documentation
Source: https://www.mintlify.com/docs/cli/analytics
View traffic, search queries, feedback, and assistant conversations from the terminal using the Mintlify CLI.
The `mint analytics` command gives you access to your [documentation analytics](/optimize/analytics) from the terminal. This is useful for scripting analytics reports, piping data into other tools, and quick checks without opening the dashboard.
## Prerequisites
You must log in to use analytics commands. Run `mint login` to authenticate with your Mintlify account.
See [Preview locally](/cli/preview#log-in-for-search-and-assistant) for details on authentication.
## View key metrics
Display a summary of views, visitors, searches, feedback, and assistant usage:
```bash theme={null}
mint analytics stats
```
Use flags to filter by date range, page, or traffic source:
* `--from`: Start date in `YYYY-MM-DD` format. Defaults to 7 days ago.
* `--to`: End date in `YYYY-MM-DD` format. Defaults to today.
* `--page`: Filter to a specific page path.
* `--humans`: Show only human traffic.
* `--agents`: Show only AI traffic.
```bash Example analytics stats flags theme={null}
mint analytics stats --from 2025-01-01 --to 2025-01-31
mint analytics stats --page /quickstart
mint analytics stats --humans
mint analytics stats --agents
```
## View search analytics
See what your users are searching for, with hit counts and click-through rates:
```bash theme={null}
mint analytics search
```
Use flags to filter by query string or page:
* `--query`: Filter by search query substring.
* `--page`: Filter to a specific page path.
```bash Example analytics search flags theme={null}
mint analytics search --query "authentication"
mint analytics search --page /api-reference
```
## View feedback
Review feedback submitted by users on your documentation pages:
```bash theme={null}
mint analytics feedback
```
Use flags to aggregate feedback by page, or filter to code snippet feedback:
* `--type`: Aggregate feedback by page or code snippet. Defaults to page.
* `--page`: Filter to a specific page path.
```bash Example analytics feedback flags theme={null}
mint analytics feedback --type page
mint analytics feedback --type code
```
## View assistant conversations
List recent conversations and conversation category buckets from the AI assistant:
```bash theme={null}
mint analytics conversation list
mint analytics conversation buckets list
```
Each list output includes an ID for each entry. Pass that ID to the corresponding `view` command to see full details:
```bash theme={null}
mint analytics conversation view
mint analytics conversation buckets view
```
## Choose an output format
All analytics commands default to `plain` output, which is tab-separated and suitable for piping to other tools. Use `--format` to change the output:
```bash theme={null}
mint analytics stats --format table # Pretty-printed table with colors
mint analytics stats --format json # Raw JSON
mint analytics stats --format graph # Horizontal bar chart
```
Use the `--agent` flag for JSON output. The CLI auto-detects agent environments when the `CLAUDECODE` environment variable is `1`.
## Set defaults with config
To avoid repeating common flags, set defaults with `mint config`. The configuration saves in `~/.config/mintlify/config.json`.
Available configuration keys:
| Key | Description |
| ----------- | -------------------------------------------------------- |
| `subdomain` | Default subdomain for analytics commands. |
| `dateFrom` | Default start date for analytics queries (`YYYY-MM-DD`). |
| `dateTo` | Default end date for analytics queries (`YYYY-MM-DD`). |
```bash Example configs theme={null}
mint config set subdomain my-docs
mint config set dateFrom 2025-01-01
```
Once set, analytics commands use these values automatically:
```bash theme={null}
# Uses the configured subdomain and dateFrom without flags
mint analytics stats
```
To view or clear a value, run:
```bash theme={null}
mint config get subdomain
mint config clear subdomain
```
# Commands
Source: https://www.mintlify.com/docs/cli/commands
Complete reference for all Mintlify CLI commands and flags.
## Global flags
These flags are available on all commands.
| Flag | Description |
| ------------------- | -------------------------------------------------- |
| `--telemetry`, `-t` | Enable or disable anonymous usage telemetry. |
| `--help`, `-h` | Display help for the command. |
| `--version`, `-v` | Display the CLI version. Alias for `mint version`. |
## `mint dev`
Start a local preview of your documentation.
```bash theme={null}
mint dev [flags]
```
| Flag | Description |
| ------------------- | -------------------------------------------------------- |
| `--port` | Port to run the local preview on. Defaults to `3000`. |
| `--no-open` | Do not open the browser automatically. |
| `--groups` | Comma-separated list of user groups to mock for preview. |
| `--disable-openapi` | Skip OpenAPI file processing to improve performance. |
| `--local-schema` | Allow locally hosted OpenAPI files served over HTTP. |
***
## `mint login`
Authenticate with your Mintlify account.
```bash theme={null}
mint login
```
Opens a browser window to complete authentication. If the browser does not open, the CLI displays a URL to open manually and a prompt to paste the authorization code. Credentials save in `~/.config/mintlify/config.json`.
***
## `mint logout`
Remove stored credentials.
```bash theme={null}
mint logout
```
***
## `mint status`
Display your current session details including CLI version, account email, organization, and configured subdomain.
```bash theme={null}
mint status
```
***
## `mint analytics`
View analytics data for your documentation. Requires authentication with `mint login`.
```bash theme={null}
mint analytics [flags]
```
All subcommands accept these shared flags:
| Flag | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--subdomain` | Documentation subdomain. Defaults to the value set with `mint config set subdomain`. |
| `--from` | Start date in `YYYY-MM-DD` format. Defaults to 7 days ago, or the value set with `mint config set dateFrom`. |
| `--to` | End date in `YYYY-MM-DD` format. Defaults to today, or the value set with `mint config set dateTo`. |
| `--format` | Output format: `plain` (default), `table`, `json`, or `graph`. |
| `--agent` | Output JSON. Equivalent to `--format json`. Also activated automatically when the `CLAUDECODE` environment variable equals `1`. |
### `mint analytics stats`
Display a summary of views, visitors, searches, feedback, and assistant usage.
```bash theme={null}
mint analytics stats [flags]
```
| Flag | Description |
| ---------- | ------------------------------- |
| `--page` | Filter to a specific page path. |
| `--humans` | Show only human traffic. |
| `--agents` | Show only AI agent traffic. |
### `mint analytics search`
Display search queries with hit counts and click-through rates.
```bash theme={null}
mint analytics search [flags]
```
| Flag | Description |
| --------- | --------------------------------- |
| `--query` | Filter by search query substring. |
| `--page` | Filter by top clicked page. |
### `mint analytics feedback`
Display feedback submitted by users.
```bash theme={null}
mint analytics feedback [flags]
```
| Flag | Description |
| -------- | ---------------------------------------------------------------------------- |
| `--type` | Feedback type: `page` (aggregate by page) or `code` (code snippet feedback). |
| `--page` | Filter to a specific page path. |
### `mint analytics conversation`
View assistant conversation data.
```bash theme={null}
mint analytics conversation [flags]
```
#### `mint analytics conversation list`
List assistant conversations. Each entry includes a conversation ID.
```bash theme={null}
mint analytics conversation list [flags]
```
| Flag | Description |
| -------- | --------------------------------------------------------------- |
| `--page` | Filter conversations that reference a specific page in sources. |
#### `mint analytics conversation view `
View a single conversation by ID. Use `mint analytics conversation list` to get IDs.
```bash theme={null}
mint analytics conversation view
```
#### `mint analytics conversation buckets list`
List grouped conversation categories. Each entry includes a bucket ID.
```bash theme={null}
mint analytics conversation buckets list
```
#### `mint analytics conversation buckets view `
View conversations in a category bucket. Use `mint analytics conversation buckets list` to get IDs.
```bash theme={null}
mint analytics conversation buckets view
```
***
## `mint config`
Manage persistent default values for CLI commands. The configuration saves in `~/.config/mintlify/config.json`.
```bash theme={null}
mint config [value]
```
| Subcommand | Description |
| ------------------- | ------------------------------ |
| `set ` | Set a configuration value. |
| `get ` | Display a configuration value. |
| `clear ` | Remove a configuration value. |
### Configuration keys
| Key | Description | Used by |
| ----------- | -------------------------------------------------------- | ---------------- |
| `subdomain` | Default documentation subdomain. | `mint analytics` |
| `dateFrom` | Default start date for analytics queries (`YYYY-MM-DD`). | `mint analytics` |
| `dateTo` | Default end date for analytics queries (`YYYY-MM-DD`). | `mint analytics` |
***
## `mint broken-links`
Check for broken internal links in your documentation.
```bash theme={null}
mint broken-links [flags]
```
The command excludes files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files report as broken.
| Flag | Description |
| ------------------ | -------------------------------------------------------------------------------- |
| `--check-anchors` | Also validate anchor links (for example, `/page#section`) against heading slugs. |
| `--check-external` | Also check external URLs for broken links. |
| `--check-snippets` | Also check links inside `` components. |
***
## `mint a11y`
Check for accessibility issues in your documentation.
```bash theme={null}
mint a11y [flags]
```
Checks color contrast ratios and missing alt text on images and videos.
| Flag | Description |
| ----------------- | ----------------------------- |
| `--skip-contrast` | Skip color contrast checks. |
| `--skip-alt-text` | Skip missing alt text checks. |
***
## `mint validate`
Validate your documentation build in strict mode. Exits with an error if there are any warnings or errors. Includes automatic validation of OpenAPI specifications referenced in your `docs.json`.
```bash theme={null}
mint validate [flags]
```
| Flag | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `--groups` | Comma-separated list of user groups to mock for validation. |
| `--disable-openapi` | Skip OpenAPI file processing and validation. |
| `--local-schema` | Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production. |
The standalone `mint openapi-check` command is deprecated. Use `mint validate` instead.
***
## `mint workflow`
Create a [workflow](/agent/workflows) file interactively.
```bash theme={null}
mint workflow
```
The CLI prompts for a name, trigger type, and other settings, then creates a `.md` file in `.mintlify/workflows/`.
***
## `mint export`
Export your documentation as a self-contained zip archive for offline viewing and distribution.
```bash theme={null}
mint export [flags]
```
| Flag | Description |
| ------------------- | -------------------------------------------------------------------- |
| `--output` | Output filename. Defaults to `export.zip`. |
| `--groups` | Comma-separated list of user groups to include restricted pages for. |
| `--disable-openapi` | Skip OpenAPI processing. |
See [Offline export](/deploy/export) for details.
***
## `mint new`
Create a new documentation project from the Mintlify starter template.
```bash theme={null}
mint new [directory] [flags]
```
| Flag | Description |
| --------- | ------------------------------------------------------------------------------------------------- |
| `--name` | Project name. The CLI prompts for this if not provided in interactive mode. |
| `--theme` | Project [theme](/customize/themes). The CLI prompts for this if not provided in interactive mode. |
| `--force` | Overwrite the directory without prompting. |
***
## `mint update`
Update the CLI to the latest version.
```bash theme={null}
mint update
```
***
## `mint version`
Display the current CLI and client versions.
```bash theme={null}
mint version
```
***
## Coming soon
These commands are available to run but are not yet functional. Running them records your interest through CLI telemetry and helps prioritize what ships next.
| Command | Description |
| ------------- | ------------------------------- |
| `mint ai` | AI-powered documentation tools. |
| `mint test` | Documentation testing. |
| `mint signup` | Account sign-up from the CLI. |
| `mint mcp` | MCP server for documentation. |
***
## Telemetry
The CLI collects anonymous usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, and architecture. Mintlify does **not** collect personally identifiable information, project content, or file paths.
By default, the CLI collects telemetry data. You can opt out at any time using the `--telemetry` flag:
```bash theme={null}
# Disable telemetry
mint --telemetry false
# Re-enable telemetry
mint --telemetry true
```
You can also disable telemetry by setting one of these environment variables:
| Variable | Value | Description |
| ----------------------------- | ----- | -------------------------------------------------------------------------------------------- |
| `MINTLIFY_TELEMETRY_DISABLED` | `1` | Disable Mintlify CLI telemetry. |
| `DO_NOT_TRACK` | `1` | Disable telemetry using the [Console Do Not Track](https://consoledonottrack.com/) standard. |
Your preference saves in `~/.config/mintlify/config.json` and persists across CLI sessions.
# Mintlify CLI
Source: https://www.mintlify.com/docs/cli/index
The Mintlify CLI lets you preview documentation locally, test changes in real time, analyze site performance, and run quality checks before deploying to production.
## About the CLI
Use the [CLI](https://www.npmjs.com/package/mint) to preview your documentation locally, test changes in real time, analyze site performance, and run quality checks before deploying to production.
The CLI runs on your machine and connects to your Mintlify deployment when you need live data.
### Preview locally
Run `mint dev` to preview your documentation at `localhost:3000`. As you write and update your content, changes appear in real time without deploying. Log in to enable search and the AI assistant in your local preview.
### Analyze your documentation
Run `mint analytics` to view traffic, search queries, user feedback, and AI assistant conversations directly from the terminal. Useful for quick checks, scripting, and piping data into other tools.
### Run quality checks
Run `mint broken-links` to find broken links, `mint a11y` to check accessibility, and `mint validate` to validate your documentation build before it reaches production.
### Manage configuration
Run `mint config` to set persistent defaults like your documentation subdomain and date ranges for analytics commands.
## Next steps
* [Install the CLI](/cli/install): Get the CLI installed and ready to use.
* [Preview locally](/cli/preview): Run a local development server with search and assistant support.
* [Analyze your documentation](/cli/analytics): View analytics data from the terminal.
* [Commands](/cli/commands): Complete reference for all commands and flags.
# Install the CLI
Source: https://www.mintlify.com/docs/cli/install
Install the Mintlify CLI to preview documentation locally, test changes in real time, and catch build errors before deploying to production.
## Prerequisites
* [Node.js](https://nodejs.org/en) v20.17.0+ (LTS versions recommended)
## Install the CLI
```bash npm theme={null}
npm i -g mint
```
```bash pnpm theme={null}
pnpm add -g mint
```
## Create a new project
To create a new documentation project from the Mintlify starter template, run the following command:
```bash theme={null}
mint new [directory]
```
If you do not specify a directory, the CLI prompts you to create a new subdirectory or overwrite the current directory.
Overwriting the current directory deletes any existing files.
| Flag | Description |
| --------- | ----------------------------------------------------------------------------- |
| `--name` | Project name. The CLI prompts for this if not provided. |
| `--theme` | Project [theme](/customize/themes). The CLI prompts for this if not provided. |
| `--force` | Overwrite the current directory without prompting. |
In non-interactive environments such as CI/CD pipelines or AI coding agents, you must provide `--name` and `--theme` flags.
## Update
If your local preview is out of sync with your deployed documentation, update the CLI to the latest version:
```bash theme={null}
mint update
```
If `mint update` is not available on your version, reinstall the CLI with the latest version:
```bash npm theme={null}
npm i -g mint@latest
```
```bash pnpm theme={null}
pnpm add -g mint@latest
```
## Formatting
For syntax highlighting and code formatting in MDX files, we recommend using the following extensions:
* **Cursor, Windsurf, VS Code**: [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
* **JetBrains**: [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm)
## 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, first run `npm ls -g` to see what packages are globally installed. If you don't use npm, try `which mint` to locate the installation.
If you have both a `mint` and a `mintlify` package installed, uninstall `mintlify`:
```bash theme={null}
npm uninstall -g mintlify
npm cache clean --force
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.
**Solution**: Ask your IT administrator to add `releases.mintlify.com` to your network allowlist.
# Preview locally
Source: https://www.mintlify.com/docs/cli/preview
Run a local preview of your documentation with live reload, search, and AI assistant support.
## Start the local preview
Navigate to your documentation directory containing your `docs.json` file and run:
```bash theme={null}
mint dev
```
The local preview starts at `http://localhost:3000`. As you edit, changes appear in real time.
By default, the preview opens automatically in your browser. To prevent the browser from opening, use the `--no-open` flag:
```bash theme={null}
mint dev --no-open
```
To generate a preview without installing the CLI globally, run:
```bash theme={null}
npx mint dev
```
## Log in for search and assistant
You must authenticate the CLI with your Mintlify account to enable search and the [assistant](/ai/assistant).
```bash theme={null}
mint login
```
After you authenticate with the `mint login` command, the CLI stores your credentials in `~/.config/mintlify/config.json` so you stay logged in across sessions.
Once logged in, run `mint dev` to start the local preview with search and the assistant enabled. The assistant uses the same indexed content as your deployed documentation site.
To check your authentication status, run:
```bash theme={null}
mint status
```
To log out, run:
```bash theme={null}
mint logout
```
## Custom ports
By default, the CLI uses port 3000. To use a different port, use the `--port` flag:
```bash theme={null}
mint dev --port 3333
```
If the port is already in use, the CLI automatically tries the next available port.
## Skip OpenAPI processing
If you have many OpenAPI files, skip OpenAPI processing during local development to improve performance with the `--disable-openapi` flag:
```bash theme={null}
mint dev --disable-openapi
```
## Preview as a specific group
If you use group-based access control, preview as a specific authentication group with the `--groups` flag:
```bash theme={null}
mint dev --groups admin
```
See [Authentication setup](/deploy/authentication-setup#control-access-with-groups) for more information on groups.
# Accordions
Source: https://www.mintlify.com/docs/components/accordions
Use the accordion component to show and hide content sections, organize related information, and enable progressive disclosure in your docs.
Accordions allow users to expand and collapse content sections. Use accordions for progressive disclosure and to organize information.
When you open an accordion, the URL hash updates, which allows you to share direct links to specific accordion sections.
## Single accordion
You can put any content in here, including other components, like code:
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx Accordion example theme={null}
You can put any content in here, including other components, like code:
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
## Accordion groups
Group related accordions together using ``. This creates a cohesive section of accordions that can be individually expanded or collapsed.
You can put other components inside Accordions.
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
Add icons to make accordions more visually distinct and scannable.
Keep related content organized into groups.
````mdx Accordion Group Example theme={null}
You can put other components inside Accordions.
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
Add icons to make accordions more visually distinct and scannable.
Keep related content organized into groups.
````
## Properties
Title in the Accordion preview.
Detail below the title in the Accordion preview.
Whether the Accordion is open by default.
A custom ID for the accordion used for anchor linking. If omitted, defaults to the same value as `title`.
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
# Badge
Source: https://www.mintlify.com/docs/components/badge
Use the badge component to highlight status indicators, version labels, or metadata inline with customizable colors and hover tooltips.
Use badges to display status indicators, labels, or metadata. Place badges inline within text or as standalone elements.
## Basic badge
Badge
```mdx theme={null}
Badge
```
## Colors
Badges support multiple color variants to convey different meanings.
BadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadge
```mdx theme={null}
BadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadge
```
## Sizes
Badges come in four sizes to match your content hierarchy.
BadgeBadgeBadgeBadge
```mdx theme={null}
BadgeBadgeBadgeBadge
```
## Shapes
Choose between rounded corners or pill-shaped badges.
BadgeBadge
```mdx theme={null}
BadgeBadge
```
## Icons
Add icons to badges for additional context.
BadgeBadgeBadge
```mdx theme={null}
BadgeBadgeBadge
```
## Stroke variant
Use the stroke variant for a more subtle appearance.
BadgeBadgeBadgeBadge
```mdx theme={null}
BadgeBadgeBadgeBadge
```
## Disabled state
Disable badges to indicate inactive or unavailable states.
BadgeBadge
```mdx theme={null}
BadgeBadge
```
## Inline usage
Badges work naturally within text content. For example, this feature requires a Premium subscription, or this API endpoint returns JSON format.
```mdx theme={null}
This feature requires a Premium subscription.
```
## Combined properties
Combine multiple properties for custom badge styles.
PremiumVerifiedBeta
```mdx theme={null}
PremiumVerifiedBeta
```
## Properties
Badge color variant.
Options: `gray`, `blue`, `green`, `yellow`, `orange`, `red`,
`purple`, `white`, `surface`, `white-destructive`, `surface-destructive`.
Badge size.
Options: `xs`, `sm`, `md`, `lg`.
Badge shape.
Options: `rounded`, `pill`.
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
Display badge with an outline instead of filled background.
Display badge in a disabled state with reduced opacity.
Additional CSS classes to apply to the badge.
# Banner
Source: https://www.mintlify.com/docs/components/banner
Add a dismissible banner at the top of your documentation site to display important announcements, release notes, or notifications.
Use banners to display important announcements, updates, or notifications across your entire documentation site. Banners appear at the top of every page, support Markdown formatting, and you can make them dismissible. Banners use the color defined by the `colors.dark` property in your `docs.json`.
To add a banner, use the `banner` property in your `docs.json`:
```json Product announcements wrap theme={null}
"banner": {
"content": "🚀 Version 2.0 is now live! See our [changelog](/changelog) for details.",
"dismissible": true
}
```
```json Maintenance notices wrap theme={null}
"banner": {
"content": "⚠️ Scheduled maintenance: API will be unavailable December 15, 2-4 AM UTC",
"dismissible": false
}
```
```json Required actions wrap theme={null}
"banner": {
"content": "**Action required:** Migrate to our new version by January 1. [Migration guide](/migration)",
"dismissible": true
}
```
You can also configure banners per language by setting `banner` in `navigation.languages`. See [Language-specific banners](#language-specific-banners).
## Properties
The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.
Whether users can dismiss the banner. When `true`, a close button appears. If a user closes the banner, it stays hidden for them until you update the banner content. Defaults to `false`.
## Language-specific banners
Configure different banner content for each language in your documentation. Define language-specific banners in the `navigation.languages` array in your `docs.json`.
```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"]
}
]
},
{
"language": "es",
"banner": {
"content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog) para más detalles.",
"dismissible": true
},
"groups": [
{
"group": "Getting started",
"pages": ["es/overview", "es/quickstart"]
}
]
}
]
},
"banner": {
"content": "🚀 Version 2.0 is now live!",
"dismissible": true
}
}
```
### Fallback behavior
Banners follow a priority order when determining which content to display:
1. **Language-specific banner**: If the current language has a `banner` configuration, it takes priority.
2. **Global banner**: If no language-specific banner exists, display the global `banner`.
# Callouts
Source: https://www.mintlify.com/docs/components/callouts
Use callout components to highlight important information, warnings, and tips in your documentation.
Style callouts as Note, Warning, Info, Tip, Check, Danger, or create your own callout:
This adds a note in the content
```mdx theme={null}
This adds a note in the content
```
This raises a warning to watch out for
```mdx theme={null}
This raises a warning to watch out for
```
This draws attention to important information
```mdx theme={null}
This draws attention to important information
```
This suggests a helpful tip
```mdx theme={null}
This suggests a helpful tip
```
This brings us a checked status
```mdx theme={null}
This brings us a checked status
```
This is a danger callout
```mdx theme={null}
This is a danger callout
```
This is a custom callout
```mdx wrap theme={null}
This is a custom callout
```
## Custom callout properties
The generic `Callout` component supports custom icons and colors. The typed callouts (`Note`, `Warning`, `Info`, `Tip`, `Check`, `Danger`) use preset icons and colors and only accept `children`.
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
Custom color as a hex code (for example, `#FFC107`). Sets the border, background tint, and text color of the callout.
# Cards
Source: https://www.mintlify.com/docs/components/cards
Use card components to highlight key points, create navigation links, and organize content with icons and customizable layouts.
Use cards to create visual containers for content. Cards are flexible containers that can include text, icons, images, and links.
## Basic card
This is how you use a card with an icon and a link. Clicking on this card
brings you to the Columns page.
```mdx Card example theme={null}
This is how you use a card with an icon and a link. Clicking on this card
brings you to the Columns page.
```
## Card variations
Cards support several layout and styling options to fit different content needs.
### Horizontal layout
Add the `horizontal` property to display cards in a more compact, horizontal layout.
This is an example of a horizontal card.
```mdx Horizontal card example theme={null}
This is an example of a horizontal card.
```
### Image cards
Add an `img` property to display an image at the top of the card.
This is an example of a card with an image.
```mdx Image card example theme={null}
This is an example of a card with an image.
```
### Link cards with custom CTAs
You can customize the call-to-action text and control whether an arrow appears. By default, arrows only show for external links.
This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
```mdx Link card example theme={null}
This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
```
## Group cards
Use the [Columns component](/components/columns) to organize multiple cards side by side. The Columns component supports one to four columns and automatically adjusts for smaller screens.
This is the first card.
This is the second card.
```mdx Columns example theme={null}
This is the first card.
This is the second card.
```
## Properties
The title displayed on the card.
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
Icon color as a hex code (for example, `#FF6B6B`).
URL to navigate to when the card is clicked.
Display the card in a compact horizontal layout.
URL or local path to an image displayed at the top of the card.
Custom text for the action button.
Show or hide the link arrow icon.
# Code groups
Source: https://www.mintlify.com/docs/components/code-groups
Use code groups to display multiple code examples in a tabbed interface and compare implementations across different languages.
Use the `CodeGroup` component to display multiple code blocks in a tabbed interface, allowing users to compare implementations across different programming languages or see alternative approaches for the same task.
```javascript helloWorld.js theme={null}
console.log("Hello World");
```
```python hello_world.py theme={null}
print('Hello World!')
```
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
Code groups inherit global styling from your `docs.json` file. Customize your theme using `styling.codeblocks`. See [Settings](/organize/settings-appearance#styling) for configuration options.
Code groups automatically synchronize with other code groups and [tabs](/components/tabs) on the same page when their labels match. When you select a language in one code group, all tabs and code groups with matching labels update to show the same language.
## Create code groups
To create a code group, wrap multiple code blocks with `` tags. Each code block must include a title, which becomes the tab label.
````mdx theme={null}
```javascript helloWorld.js
console.log("Hello World");
```
```python hello_world.py
print('Hello World!')
```
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
## Language dropdown
You can replace the tabs in a code group with a dropdown menu to toggle between languages using the `dropdown` prop.
```javascript helloWorld.js theme={null}
console.log("Hello World");
```
```python hello_world.py theme={null}
print('Hello World!')
```
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx highlight=1 theme={null}
```javascript helloWorld.js
console.log("Hello World");
```
```python hello_world.py
print('Hello World!')
```
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
# Color
Source: https://www.mintlify.com/docs/components/color
Display color swatches with hex values and click-to-copy capability using the color component for design system and branding documentation.
Use the Color component to showcase color palettes in your documentation. Display colors in a compact grid or organize them in a table with labeled rows.
## Compact variant
Display colors in a simple grid layout with color names and values.
```mdx Compact example theme={null}
```
## Table variant
Organize colors into labeled rows for design system documentation.
```mdx Table example theme={null}
```
## Color formats
The component supports all CSS color formats including hex, rgb, rgba, hsl, and oklch.
```mdx Color formats example theme={null}
```
## Theme-aware colors
Define different colors for light and dark modes using an object with `light` and `dark` properties.
```mdx Theme-aware example theme={null}
```
## Properties
### Color
Display style for the color palette. Options: `compact` or `table`.
Color items or rows to display.
### Color.Row
Label for the row of colors.
Color items to display in the row.
### Color.Item
Name or label for the color.
Color value in any CSS format, or an object with light and dark mode values.
# Columns
Source: https://www.mintlify.com/docs/components/columns
Arrange cards and other components in a responsive multi-column grid layout with the columns component, including customizable column counts.
The `Columns` component lets you arrange content in a responsive grid layout. It's most often used to put cards in a grid, by specifying the number of grid columns. You can also use the `Column` sub-component to wrap arbitrary content. Columns are responsive and automatically adjust for smaller screens.
Set up your project with our quickstart guide.
Explore endpoints, parameters, and examples for your API.
```mdx Columns example theme={null}
Set up your project with our quickstart guide.
Explore endpoints, parameters, and examples for your API.
```
## Column sub-component
Use the `Column` component to wrap text or code in individual columns. This is useful when you want to display arbitrary content side by side, not just cards or other components.
**Installation**
```bash theme={null}
npm install my-package
```
**Usage**
```javascript theme={null}
import { init } from 'my-package';
init();
```
````mdx Column sub-component example theme={null}
**Installation**
```bash
npm install my-package
```
**Usage**
```javascript
import { init } from 'my-package';
init();
```
````
## Properties
The number of columns per row. Accepts values from 1 to 4.
# Examples
Source: https://www.mintlify.com/docs/components/examples
Display code examples in the right sidebar panel on desktop devices to show request and response samples alongside API documentation.
The `` and `` components display code blocks in the right sidebar to create a two-column layout that keeps examples visible while users scroll through your content. Use these components for API documentation, but they work on all pages.
Common use cases:
* API endpoint documentation with request and response examples
* Configuration examples alongside explanatory text
* Code samples that users reference while following instructions
* Before and after examples in tutorials
On mobile devices, `` and `` components display as regular code blocks that users can scroll past.
```bash Request theme={null}
curl --request POST \
--url https://dog-api.kinduff.com/api/facts
```
```json Response theme={null}
{ "status": "success" }
```
## RequestExample
Use `` to pin code examples in the right sidebar. This component works similarly to the [CodeGroup](/components/code-groups) component, but displays the code in the sidebar instead of inline.
You can include multiple code blocks inside a single ``. Each code block must have a title attribute.
````mdx RequestExample theme={null}
```bash Request
curl --request POST \
--url https://dog-api.kinduff.com/api/facts
```
````
## ResponseExample
The `` component pins code examples in the right sidebar beneath any `` content on the same page.
````mdx ResponseExample theme={null}
```json Response
{ "status": "success" }
```
````
## Properties
Both `` and `` accept the following properties:
Display a language dropdown menu for switching between code blocks, instead of the default tab layout.
# Expandables
Source: https://www.mintlify.com/docs/components/expandables
Use the expandable component to toggle nested object properties in API documentation, showing child fields for request and response objects.
Use expandables to show and hide nested content within response fields. They are particularly useful for displaying complex object properties in API documentation.
The full name of the user
Whether the user is over 21 years old
```mdx Expandable example theme={null}
The full name of the user
Whether the user is over 21 years old
```
## Properties
The name of the object you are showing.
Set to `true` for the expandable to open when the page loads
# Fields
Source: https://www.mintlify.com/docs/components/fields
Document API request and response parameters with types, defaults, and validation rules.
Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields.
## Parameter field
The `` component is used to define parameters for your APIs or SDKs. Adding a `ParamField` automatically adds an [API Playground](/api-playground/overview).
An example of a parameter field
```mdx theme={null}
An example of a parameter field
```
### Properties
Whether the parameter is a query, path, body, or header. Followed by the
parameter name.
Expected type of the parameter's value.
Supports `number`, `string`, `boolean`, `object`.
Arrays can be defined using the `[]` suffix. For example `string[]`.
Indicate whether the parameter is required.
Indicate whether the parameter is deprecated.
Default value populated when the request value is empty
Placeholder text for the input in the playground.
Description of the parameter (Markdown-enabled).
## Response field
The `` component defines the return values of an API.
An example of a response field
```mdx theme={null}
A response field example
```
### Properties
The name of the response value.
Expected type of the response value. This can be any arbitrary string.
The default value.
Indicate whether the response is required.
Whether a field is deprecated.
Labels that are shown before the name of the field.
Labels that are shown after the name of the field.
# Frames
Source: https://www.mintlify.com/docs/components/frames
Wrap images, videos, and other components with the frame component to add styled borders, captions, and visual emphasis to your content.
Use frames to display images, diagrams, videos, or other visual content with consistent styling and optional captions. Frames center content and provide visual separation from surrounding text.
## Captions
Add additional context to an image using the optional `caption` prop. Captions appear in the frame below the image.
### Markdown in captions
Captions support markdown formatting, including links and bold text.
## Hints
Add text that precedes the frame using the optional `hint` prop. Hints appear above the frame.
## Videos
When you place a `video` element with `autoPlay` inside a frame, the frame adds `playsInline`, `loop`, and `muted` attributes.
```mdx Video with autoPlay theme={null}
```
Videos without `autoPlay` do not have any additional attributes added by default.
## Properties
Text that appears as part of the frame, centered below the content. Supports markdown formatting including links and bold text.
Text that precedes the frame.
```mdx Frame theme={null}
```
```mdx Frame with a caption theme={null}
```
```mdx Frame with markdown in caption theme={null}
```
```mdx Frame with bold text and links in caption theme={null}
```
```mdx Frame with a hint theme={null}
```
```mdx Frame with both hint and caption theme={null}
```
# Icons
Source: https://www.mintlify.com/docs/components/icons
Add icons from Font Awesome, Lucide, Tabler, or custom sources to your documentation pages using the icon component with size and color options.
Use icons from Font Awesome, Lucide, Tabler, SVGs, external URLs, or files in your project to enhance your documentation.
```mdx Icon example theme={null}
```
## Inline icons
Icons are placed inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis.
```markdown Inline icon example theme={null}
Icons are placed inline when used within a sentence, paragraph, or heading. Use icons for decoration or to add visual emphasis.
```
## Properties
The icon to display.
Options:
* [Font Awesome icon](https://fontawesome.com/icons) name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide icon](https://lucide.dev/icons) name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler icon](https://tabler.io/icons) name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
The color of the icon as a hex code (for example, `#FF5733`).
The size of the icon in pixels.
Custom CSS class name to apply to the icon.
# Overview
Source: https://www.mintlify.com/docs/components/index
Browse the full Mintlify component library for layout, emphasis, API documentation, and navigation elements available in your MDX pages.
Mintlify provides built-in MDX components for your documentation pages. Use these components to structure content, draw attention to important information, document APIs, and guide navigation.
## Structure your content
Organize related content into switchable tabbed views.
Display code examples in multiple languages.
Display sequential instructions in a numbered format.
Arrange content side by side in responsive layouts.
Create sidebar panels for supplementary content.
## Draw attention
Emphasize important information with styled alerts.
Display prominent announcements at the top of pages.
Add inline labels and status indicators.
Highlight new or updated content.
Add borders and styling to images and content.
Display additional information on hover.
## Showcase AI prompts
Display copyable AI prompts with Cursor integration.
## Show and hide content
Expandable sections for progressive disclosure of content.
Show and hide detailed content on demand.
Conditionally show content based on context.
## Document your API
Display parameter and property definitions.
Document API response structures and fields.
Show request and response examples side by side.
## Link to other pages
Highlight content with customizable containers and icons.
Display content in a grid of clickable tiles.
## Add visual context
Add visual indicators using the Lucide icon library.
Create flowcharts, sequence diagrams, and more.
Display color swatches with hex values.
Display hierarchical file and folder structures.
# Mermaid
Source: https://www.mintlify.com/docs/components/mermaid-diagrams
Create flowcharts, sequence diagrams, and other visualizations in your documentation using Mermaid syntax with automatic rendering.
[Mermaid](https://mermaid.js.org/) lets you build flowcharts, sequence diagrams, Gantt charts, and other diagrams using text and code.
For a complete list of supported diagram types and syntax, see the [Mermaid documentation](https://mermaid.js.org/intro/).
```mermaid placement="top-right" theme={null}
flowchart LR
subgraph subgraph1
direction TB
top1[top] --> bottom1[bottom]
end
subgraph subgraph2
direction TB
top2[top] --> bottom2[bottom]
end
%% ^ These subgraphs are identical, except for the links to them:
%% Link *to* subgraph1: subgraph1 direction is maintained
outside --> subgraph1
%% Link *within* subgraph2:
%% subgraph2 inherits the direction of the top-level graph (LR)
outside ---> top2
```
````mdx Mermaid flowchart example theme={null}
```mermaid placement="top-right"
flowchart LR
subgraph subgraph1
direction TB
top1[top] --> bottom1[bottom]
end
subgraph subgraph2
direction TB
top2[top] --> bottom2[bottom]
end
%% ^ These subgraphs are identical, except for the links to them:
%% Link *to* subgraph1: subgraph1 direction is maintained
outside --> subgraph1
%% Link *within* subgraph2:
%% subgraph2 inherits the direction of the top-level graph (LR)
outside ---> top2
```
````
## ELK layout support
Mintlify supports the [ELK (Eclipse Layout Kernel)](https://www.eclipse.org/elk/) layout engine for Mermaid diagrams. ELK optimizes arrangement to reduce overlapping and improve readability, which is useful for large or complex diagrams.
To use ELK layout in your Mermaid diagrams, add the `%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%` directive at the beginning of your diagram:
````mdx ELK layout example theme={null}
```mermaid
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart LR
A[Start] --> B[Process 1]
B --> C[Process 2]
B --> D[Process 3]
C --> E[End]
D --> E
```
````
## Interactive controls
All Mermaid diagrams include interactive zoom and pan controls. By default, controls appear when the diagram height exceeds 120px.
* **Zoom in/out**: Use the zoom buttons to increase or decrease the diagram scale.
* **Pan**: Use the directional arrows to move around the diagram.
* **Reset view**: Click the reset button to return to the original view.
The controls are especially useful for large or complex diagrams that don't fit entirely in the viewport.
## Properties
Show or hide the interactive controls. When set, this overrides the default behavior (controls shown when diagram height exceeds 120px).
Position of the interactive controls. Options: `top-left`, `top-right`, `bottom-left`, `bottom-right`.
### Examples
Hide controls on a diagram:
````mdx theme={null}
```mermaid actions={false}
flowchart LR
A --> B
```
````
Show controls in the top-left corner:
````mdx theme={null}
```mermaid placement="top-left"
flowchart LR
A --> B
```
````
Combine both properties:
````mdx theme={null}
```mermaid placement="top-left" actions={true}
flowchart LR
A --> B
```
````
## Syntax
To create a Mermaid diagram, write your diagram definition inside a Mermaid code block.
````mdx theme={null}
```mermaid
// Your mermaid diagram code here
```
````
# Panel
Source: https://www.mintlify.com/docs/components/panel
Customize the right side panel content on documentation pages to display supplementary information, examples, or navigation elements.
You can use the `` component to customize the right side panel of a page with any components that you want.
If a page has a `` component, any [RequestExample](/components/examples#requestexample) and [ResponseExample](/components/examples#responseexample) components must be inside ``.
The components in a `` replace a page's table of contents.
```mdx theme={null}
Pin info to the side panel. Or add any other component.
```
Pin info to the side panel. Or add any other component.
# Prompt
Source: https://www.mintlify.com/docs/components/prompt
Display pre-built AI prompts with one-click copy and Cursor integration buttons so users can quickly use prompts in their AI tools.
Use the Prompt component to display pre-built AI prompts that users can copy to their clipboard or open directly in [Cursor](https://www.cursor.com).
## Examples
You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
* Use second-person voice ("you") and active verbs.
* Start procedures with a goal-oriented heading.
* Before writing, ask clarifying questions about the end users of the documentation, their goals, and their needs.
```mdx Basic prompt example theme={null}
You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
- Use second-person voice ("you") and active verbs.
- Start procedures with a goal-oriented heading.
- Before writing, ask clarifying questions about the end users of the documentation, their goals, and their needs.
```
You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
* Use second-person voice ("you") and active verbs.
* Start procedures with a goal-oriented heading.
* Before writing, ask clarifying questions about the end users of the documentation, their goals, and their needs.
```mdx Prompt with multiple properties example theme={null}
You are a **technical writing assistant**. Write documentation that is clear, accurate, and concise.
- Use second-person voice ("you") and active verbs.
- Start procedures with a goal-oriented heading.
- Before writing, ask clarifying questions about the end users of the documentation, their goals, and their needs.
```
## Properties
The text displayed in the prompt card. Supports Markdown formatting.
The text content of the prompt. This is the text copied to the clipboard or opened in Cursor.
Array of available actions. Valid values are `"copy"` (copy to clipboard) and `"cursor"` (open in Cursor).
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
# Response fields
Source: https://www.mintlify.com/docs/components/responses
Document API response fields using the ResponseField component with type annotations, descriptions, and required or optional indicators.
Use the `` component to define the return values of an API. Many docs also use `` on pages when you need to list the types of something.
A response field example
```mdx theme={null}
A response field example
```
## Props
The name of the response value.
Expected type of the response value - this can be any arbitrary string.
The default value.
Show "required" beside the field name.
Whether a field is deprecated or not.
Labels that are shown before the name of the field
Labels that are shown after the name of the field
```mdx Response Field Example theme={null}
A response field example
```
# Steps
Source: https://www.mintlify.com/docs/components/steps
Create numbered step-by-step procedures with the steps component to guide users through sequential tasks, tutorials, and setup workflows.
Use steps to display a series of sequential actions or events. You can add as many steps as needed.
These are instructions or content that only pertain to the first step.
These are instructions or content that only pertain to the second step.
These are instructions or content that only pertain to the third step.
```mdx Steps example theme={null}
These are instructions or content that only pertain to the first step.
These are instructions or content that only pertain to the second step.
These are instructions or content that only pertain to the third step.
```
## Steps properties
A list of `Step` components.
The size of the step titles. One of `p`, `h2`, `h3`, and `h4`.
## Individual step properties
The title is the primary text for the step and shows up next to the indicator.
The content of a step either as plain text or components.
The icon to display.
Options:
* [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `fontawesome` in your `docs.json`
* [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `lucide` in your `docs.json`
* [Tabler](https://tabler.io/icons) icon name, if you have the `icons.library` [property](/organize/settings-appearance#param-icons) set to `tabler` in your `docs.json`
* URL to an externally hosted icon
* Path to an icon file in your project
* SVG code wrapped in curly braces
For custom SVG icons:
1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
2. Paste your SVG code into the SVG input field.
3. Copy the complete `` element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: `icon={}`.
5. Adjust `height` and `width` as needed.
The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.
Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
The number of the step.
The size of the step titles. One of `p`, `h2`, `h3`, and `h4`.
A custom ID for the step, used for anchor linking and table of contents navigation.
Whether to hide the anchor link for the step.
# Tabs
Source: https://www.mintlify.com/docs/components/tabs
Use the tab component to organize content into switchable panels for showing different options, platform versions, or language examples.
Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab.
☝️ Welcome to the content that you can only see inside the first tab.
You can add any number of components inside of tabs. For example, a code block:
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
✌️ Here's content that's only inside the second tab.
This one has a icon!
💪 Here's content that's only inside the third tab.
````mdx Tabs example theme={null}
☝️ Welcome to the content that you can only see inside the first tab.
You can add any number of components inside of tabs. For example, a code block:
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
✌️ Here's content that's only inside the second tab.
This one has a icon!
💪 Here's content that's only inside the third tab.
````
Tabs with matching titles stay in sync across the page. For example, if you have multiple tab groups that include a `JavaScript` tab title, selecting `JavaScript` in one tab group automatically selects `JavaScript` in the others. This helps users who choose a language or framework once see that choice reflected everywhere. Tabs also sync with [code groups](/components/code-groups) that have matching titles.
To disable tab synchronization, add `sync={false}` to a `` component.
```mdx Disable tab sync example theme={null}
This tab group operates independently.
Selecting tabs here won't affect other tab groups.
```
## Tabs properties
Set these properties on the `` wrapper component.
The index of the tab to display by default (zero-based). For example, set to `1` to show the second tab on page load.
When `true`, tabs synchronize with other tabs and code groups on the page that have matching titles. Set to `false` to make tabs independent.
Adds a bottom border and padding to the tabs container. Useful to visually separate tabbed content from the rest of the page, especially when tabs contain content of varying lengths.
## Tab properties
Set these properties on each individual `` component.
The title of the tab. Short titles are easier to navigate. Tabs with matching titles synchronize their selections.
A custom ID for the tab used for anchor linking. If not provided, defaults to the same value as `title`.
A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon.
For Font Awesome icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
# Tiles
Source: https://www.mintlify.com/docs/components/tiles
Use the tiles component to display visual previews with image thumbnails, titles, and descriptions in a responsive grid layout for your docs.
Use tiles to create visual showcase elements with a patterned background, title, and description. Tiles are ideal for displaying component previews, feature highlights, or navigation items in a grid layout.
```mdx Tile example theme={null}
```
## Grid layout
Combine tiles with the [columns component](/components/columns) to create a responsive grid of visual previews.
```mdx Grid layout example theme={null}
```
## Properties
URL to navigate to when the tile is clicked.
The title displayed below the tile preview.
A short description displayed below the title.
Content displayed inside the tile preview area, typically images or SVGs.
# Tooltips
Source: https://www.mintlify.com/docs/components/tooltips
Add tooltips to display contextual definitions and explanations when users hover over terms, abbreviations, or technical concepts in your documentation.
Use tooltips to provide additional context or definitions when a user hovers over a string of text. Tooltips can include optional call-to-action links.
**Example**: API documentation helps developers understand how to integrate with your service.
```mdx Tooltip example wrap theme={null}
API documentation helps developers understand how to integrate with your service.
```
## Properties
The text displayed in the tooltip.
Text displayed above the `tip` text.
The call-to-action text for a link within the tooltip.
URL for the call-to-action link. Required when using `cta`.
# Tree
Source: https://www.mintlify.com/docs/components/tree
Use the tree component to display hierarchical file and folder structures with collapsible nodes and syntax highlighting for path names.
Use tree components to display hierarchical structures like file systems, project directories, or nested content. The tree component supports keyboard navigation and accessibility features.
## Basic tree
```mdx Tree example theme={null}
```
## Nested folders
Create deeply nested structures by nesting `Tree.Folder` components within each other.
```mdx Nested folders example theme={null}
```
## Keyboard navigation
The tree component supports keyboard navigation.
* **Arrow keys**: Navigate up and down through visible items.
* **Right arrow**: Expand a closed folder or move to the first child of an open folder.
* **Left arrow**: Collapse an open folder or move to the parent folder.
* **Home**: Jump to the first item in the tree.
* **End**: Jump to the last visible item in the tree.
* **Enter/Space**: Toggle folder open/closed state.
* **\***: Expand all sibling folders at the current level.
* **Type-ahead search**: Type characters to jump to items that start with those characters.
## Properties
### Tree.Folder
The name of the folder displayed in the tree.
Whether the folder is expanded by default.
Whether the folder can be opened and closed. Set to false for non-interactive folders.
### Tree.File
The name of the file displayed in the tree.
# Update
Source: https://www.mintlify.com/docs/components/update
Use the update component to display product updates, release notes, and changelog entries in a structured timeline format with dates.
Use the `Update` component to display changelog entries, version updates, and release notes with consistent formatting.
## Example update
You can add anything here, like a screenshot, a code snippet, or a list of changes.
### Features
* Responsive design
* Anchor for each update
* Generated RSS feed entry for each update
## How to use
```mdx Update example theme={null}
This is an update with a label, description, and tag.
```
Use multiple `Update` components to create [changelogs](/create/changelogs).
Update components automatically generate RSS feed entries. The entries contain pure Markdown only--components, code blocks, inline code, and raw HTML elements are not included.
If your update includes components or HTML, use the `rss` prop to provide alternative text for RSS subscribers.
```mdx Custom RSS content theme={null}
## New dashboard
Check out our redesigned dashboard with improved navigation.
```
## Props
Label for the update. Appears to the left of the update and creates an anchor link. Labels should be unique.
Tags for the update. Shown as filters in the right side panel.
Description of the update. Appears below the label and tag.
Update components automatically generate RSS feed entries. Use the `rss` property to create a single RSS feed entry with a custom title and description.
If not provided:
* Updates with Markdown headings create a separate RSS feed entry for each heading.
* Updates without Markdown headings create a single RSS feed entry using the `label` as the title.
Custom title for the RSS feed entry.
Custom description for the RSS feed entry.
# View
Source: https://www.mintlify.com/docs/components/view
Use the view component to create switchable content panels for different programming languages, frameworks, or configuration alternatives.
Use the `View` component to create content that changes based on the selected view in a multi-view dropdown. This is particularly useful for showing code examples or documentation specific to different programming languages or frameworks.
Use one view component per language per page. Use [tabs](/components/tabs) for procedures that differ by language and [code groups](/components/code-groups) for code examples that differ by language.
This content is only visible when JavaScript is selected.
```javascript theme={null}
console.log("Hello from JavaScript!");
```
This content is only visible when Python is selected.
```python theme={null}
print("Hello from Python!")
```
## Example
````mdx JavaScript and Python views theme={null}
This content is only visible when JavaScript is selected.
```javascript
console.log("Hello from JavaScript!");
```
This content is only visible when Python is selected.
```python
print("Hello from Python!")
```
````
## Table of contents behavior
The table of contents automatically updates to show only the headings for the currently selected view. When you switch between views using the multi-view dropdown, the table of contents refreshes to display the relevant headings for that view.
If you have different heading structures in each view, users only see the headings that are relevant to their selected language or framework.
## Properties
The title that identifies this view. Must match one of the options in the multi-view dropdown.
A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon.
For Font Awesome icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
# Changelogs
Source: https://www.mintlify.com/docs/create/changelogs
Create product changelogs with date-based entries, RSS feed support, and subscriber notifications to keep users informed about updates.
Create a changelog for your docs by adding [Update components](/components/update) to a page.
Check out the [Mintlify changelog](/changelog) as an example: you can include links, images, text, and demos of your new features in each update.
## Setting up your changelog
1. Create a new page in your docs such as `changelog.mdx` or `updates.mdx`.
2. Add your changelog page to your navigation scheme in your `docs.json`.
Add an `Update` for each changelog entry.
Include relevant information like feature releases, bug fixes, or other announcements.
```mdx Example changelog.mdx theme={null}
---
title: "Changelog"
description: "Product updates and announcements"
---
Added a new Wintergreen flavor.
Released a new version of the Spearmint flavor, now with 10% more mint.
Released a new version of the Spearmint flavor.
```
## Customizing your changelog
Control how people navigate your changelog and stay up to date with your product information.
### Table of contents
Each `label` property for an `Update` automatically creates an entry in the right sidebar's table of contents. This is the default navigation for your changelog.
### Tag filters
Add `tags` to your `Update` components to replace the table of contents with tag filters. Users can filter the changelog by selecting one or more tags:
```mdx Tag filters example wrap theme={null}
Added a new Wintergreen flavor.
Released a new version of the Spearmint flavor, now with 10% more mint.
Released a new version of the Spearmint flavor.
Deprecated the Peppermint flavor.
Released a new version of the Spearmint flavor.
```
Using `custom`, `center`, or `wide` page modes hides the table of contents and changelog filters. Learn more about [page modes](/organize/pages#page-mode).
### Subscribable changelogs
RSS feeds are only available on public documentation.
Use `Update` components to create a subscribable RSS feed at your page URL with `/rss.xml` appended. For example, `mintlify.com/docs/changelog/rss.xml`.
The RSS feed publishes entries when you add new `Update` components and when modify headings inside of existing `Update` components.
RSS feed entries contain pure Markdown only. They exclude components, code, and HTML elements. Use the `rss` property to provide alternative text descriptions for RSS subscribers when your updates contain excluded content.
```xml Example RSS feed theme={null}
<![CDATA[Product updates]]>
https://mintlify.com/docs
RSS for NodeMon, 21 Jul 2025 21:21:47 GMThttps://mintlify.com/docs<![CDATA[June 2025]]>
https://mintlify.com/docs/changelog#june-2025
https://mintlify.com/docs/changelog#june-2025Mon, 23 Jun 2025 16:54:22 GMT
```
RSS feeds can integrate with Slack, email, or other subscription tools to notify users of product changes. Some options include:
* [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack)
* [Email](https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email) via Zapier
* Discord bots like [Readybot](https://readybot.io) or [RSS Feeds to Discord Bot](https://rss.app/en/bots/rssfeeds-discord-bot)
To make the RSS feed discoverable, you can display an RSS icon button that links to the feed at the top of the page. Add `rss: true` to the page frontmatter:
```mdx theme={null}
---
rss: true
---
```
# Format code
Source: https://www.mintlify.com/docs/create/code
Format code in your documentation with syntax highlighting, line numbers, diffs, copy buttons, and interactive code group features in MDX.
## Adding code samples
You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more.
### Inline code
To denote a `word` or `phrase` as code, enclose it in backticks (\`).
```mdx theme={null}
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
### Code blocks
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Code blocks are copyable, and if you have the assistant enabled, users can ask AI to explain the code.
Specify the programming language for syntax highlighting and to enable meta options. Add any meta options, like a title or icon, after the language.
```java HelloWorld.java example icon=java lines theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx Format theme={null}
```java HelloWorld.java example lines icon="java"
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
## Code block options
Add meta options to your code blocks to customize their appearance.
You must specify a programming language for a code block before adding any other meta options.
### Option syntax
* **String and boolean options**: Wrap with `""`, `''`, or no quotes.
* **Expression options**: Wrap with `{}`, `""`, or `''`.
### Syntax highlighting
Enable syntax highlighting by specifying the programming language after the opening backticks of a code block.
We use [Shiki](https://shiki.style/) for syntax highlighting and support all available languages. See the full list of [languages](https://shiki.style/languages) in Shiki's documentation.
Customize code block themes globally using `styling.codeblocks` in your `docs.json` file. Set simple themes like `system` or `dark`, or configure custom [Shiki themes](https://shiki.style/themes) for light and dark modes. See [Settings](/organize/settings-appearance#styling) for configuration options.
```java Syntax highlighting example theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx Format theme={null}
```java Syntax highlighting example
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
For custom themes, set your theme in `docs.json` to `"css-variables"` and override syntax highlighting colors using CSS variables with the `--mint-` prefix.
The following variables are available:
**Basic colors**
* `--mint-color-text`: Default text color
* `--mint-color-background`: Background color
**Token colors**
* `--mint-token-constant`: Constants and literals
* `--mint-token-string`: String values
* `--mint-token-comment`: Comments
* `--mint-token-keyword`: Keywords
* `--mint-token-parameter`: Function parameters
* `--mint-token-function`: Function names
* `--mint-token-string-expression`: String expressions
* `--mint-token-punctuation`: Punctuation marks
* `--mint-token-link`: Links
**ANSI colors**
* `--mint-ansi-black`, `--mint-ansi-black-dim`
* `--mint-ansi-red`, `--mint-ansi-red-dim`
* `--mint-ansi-green`, `--mint-ansi-green-dim`
* `--mint-ansi-yellow`, `--mint-ansi-yellow-dim`
* `--mint-ansi-blue`, `--mint-ansi-blue-dim`
* `--mint-ansi-magenta`, `--mint-ansi-magenta-dim`
* `--mint-ansi-cyan`, `--mint-ansi-cyan-dim`
* `--mint-ansi-white`, `--mint-ansi-white-dim`
* `--mint-ansi-bright-black`, `--mint-ansi-bright-black-dim`
* `--mint-ansi-bright-red`, `--mint-ansi-bright-red-dim`
* `--mint-ansi-bright-green`, `--mint-ansi-bright-green-dim`
* `--mint-ansi-bright-yellow`, `--mint-ansi-bright-yellow-dim`
* `--mint-ansi-bright-blue`, `--mint-ansi-bright-blue-dim`
* `--mint-ansi-bright-magenta`, `--mint-ansi-bright-magenta-dim`
* `--mint-ansi-bright-cyan`, `--mint-ansi-bright-cyan-dim`
* `--mint-ansi-bright-white`, `--mint-ansi-bright-white-dim`
**Custom syntax highlighting**
Add syntax highlighting for languages not included in Shiki's default set by providing custom TextMate grammar files. Create a JSON file following the [TextMate grammar format](https://macromates.com/manual/en/language_grammars), then reference it in your `docs.json`. You can add multiple custom languages by including additional paths in the array.
```json docs.json theme={null}
{
"styling": {
"codeblocks": {
"languages": {
"custom": ["/languages/my-custom-language.json"]
}
}
}
}
```
### Twoslash
In JavaScript and TypeScript code blocks, use `twoslash` to enable interactive type information. Users can hover over variables, functions, and parameters to see types and errors like in an IDE.
```ts twoslash Twoslash example theme={null}
type Pet = "cat" | "dog" | "hamster";
function adoptPet(name: string, type: Pet) {
return `${name} the ${type} is now adopted!`;
}
// Hover to see the inferred types
const message = adoptPet("Mintie", "cat");
```
````mdx Format theme={null}
```ts twoslash Twoslash example
type Pet = "cat" | "dog" | "hamster";
function adoptPet(name: string, type: Pet) {
return `${name} the ${type} is now adopted!`;
}
// Hover to see the inferred types
const message = adoptPet("Mintie", "cat");
```
````
### Title
Add a title to label your code example. Place the title after the language identifier. Use `title="Your title"` or a string on a single line. Titles can contain multiple words and file paths.
```javascript Example title theme={null}
const hello = "world";
```
````mdx Format theme={null}
```javascript Example title
const hello = "world";
```
````
### Icon
Add an icon to your code block using the `icon` property. See [Icons](/components/icons) for all available options.
```javascript Icon example icon=square-js theme={null}
const hello = "world";
```
````mdx Format theme={null}
```javascript Icon example icon="square-js"
const hello = "world";
```
````
### Line highlighting
Highlight specific lines in your code blocks using `highlight` with the line numbers or ranges you want to highlight.
```javascript Line highlighting example {1,2,5} theme={null}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx Format theme={null}
```javascript Line highlighting example highlight={1-2,5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
### Line focusing
Focus on specific lines in your code blocks using `focus` with line numbers or ranges.
```javascript Line focusing example focus=2,4,5 theme={null}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx Format theme={null}
```javascript Line focusing example focus={2,4-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
### Show line numbers
Display line numbers on the left side of your code block using `lines`.
```javascript Show line numbers example lines theme={null}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx Format theme={null}
```javascript Show line numbers example lines
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
### Expandable
Allow users to expand and collapse long code blocks using `expandable`.
```python Expandable example expandable theme={null}
from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass
@dataclass
class Book:
title: str
author: str
isbn: str
checked_out: bool = False
due_date: Optional[datetime] = None
class Library:
def __init__(self):
self.books: Dict[str, Book] = {}
self.checkouts: Dict[str, List[str]] = {} # patron -> list of ISBNs
def add_book(self, book: Book) -> None:
if book.isbn in self.books:
raise ValueError(f"Book with ISBN {book.isbn} already exists")
self.books[book.isbn] = book
def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None:
if patron not in self.checkouts:
self.checkouts[patron] = []
book = self.books.get(isbn)
if not book:
raise ValueError("Book not found")
if book.checked_out:
raise ValueError("Book is already checked out")
if len(self.checkouts[patron]) >= 3:
raise ValueError("Patron has reached checkout limit")
book.checked_out = True
book.due_date = datetime.now() + timedelta(days=days)
self.checkouts[patron].append(isbn)
def return_book(self, isbn: str) -> float:
book = self.books.get(isbn)
if not book or not book.checked_out:
raise ValueError("Book not found or not checked out")
late_fee = 0.0
if datetime.now() > book.due_date:
days_late = (datetime.now() - book.due_date).days
late_fee = days_late * 0.50
book.checked_out = False
book.due_date = None
# Remove from patron's checkouts
for patron, books in self.checkouts.items():
if isbn in books:
books.remove(isbn)
break
return late_fee
def search(self, query: str) -> List[Book]:
query = query.lower()
return [
book for book in self.books.values()
if query in book.title.lower() or query in book.author.lower()
]
def main():
library = Library()
# Add some books
books = [
Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"),
Book("1984", "George Orwell", "978-0-452-28423-4"),
]
for book in books:
library.add_book(book)
# Checkout and return example
library.checkout_book("978-0-261-10295-4", "patron123")
late_fee = library.return_book("978-0-261-10295-4")
print(f"Late fee: ${late_fee:.2f}")
if __name__ == "__main__":
main()
```
````text Format theme={null}
```python Expandable example expandable
from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass
# ...
if __name__ == "__main__":
main()
```
````
### Wrap
Enable text wrapping for long lines using `wrap`. This prevents horizontal scrolling and makes long lines easier to read.
```javascript Wrap example wrap theme={null}
const greeting =
"Hello, World! I am a long line of text that will wrap to the next line.";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx Format theme={null}
```javascript Wrap example wrap
const greeting =
"Hello, World! I am a long line of text that will wrap to the next line.";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
### Diff
Show a visual diff of added or removed lines in your code blocks. Added lines are highlighted in green and removed lines are highlighted in red.
Add `[!code ++]` or `[!code --]` inside a comment at the end of a line to mark it as added or removed. Use your language's comment syntax:
| Language | Added | Removed |
| ---------------------------------------------- | --------------------- | --------------------- |
| JavaScript, TypeScript, Java, C, C++, Go, Rust | `// [!code ++]` | `// [!code --]` |
| Python, Ruby, Bash, YAML | `# [!code ++]` | `# [!code --]` |
| HTML, XML | `` | `` |
| CSS | `/* [!code ++] */` | `/* [!code --] */` |
| SQL, Lua | `-- [!code ++]` | `-- [!code --]` |
For multiple consecutive lines, add a colon and the number of lines:
* `// [!code ++:3]`: Mark the current line plus the next two lines as added.
* `# [!code --:5]`: Mark the current line plus the next four lines as removed.
```js JavaScript diff lines theme={null}
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
```python Python diff lines theme={null}
def greet():
print("Hello, World!") # [!code --]
print("Hello, Mintlify!") # [!code ++]
greet()
```
````text JavaScript format theme={null}
```js JavaScript diff lines
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
````
````text Python format theme={null}
```python Python diff lines
def greet():
print("Hello, World!") # [!code --]
print("Hello, Mintlify!") # [!code ++]
greet()
```
````
## CodeBlock component
Use the `` component in custom React components to programmatically render code blocks with the same styling and features as markdown code blocks.
### Props
The programming language for syntax highlighting.
The filename to display in the code block header.
The icon to display in the code block header. See [Icons](/components/icons)
for available options.
Whether to show line numbers.
Whether to wrap the code block.
Whether to expand the code block.
The lines to highlight. Provide a stringified array of numbers. Example:
`"[1,3,4,5]"`.
The lines to focus on. Provide a stringified array of numbers. Example:
`"[1,3,4,5]"`.
### Example
```jsx theme={null}
export const CustomCodeBlock = ({
filename,
icon,
language,
highlight,
children,
}) => {
return (
{children}
);
};
```
# Files
Source: https://www.mintlify.com/docs/create/files
Serve static assets like images, videos, PDFs, and data files from your documentation repository with automatic optimization and CDN delivery.
Mintlify automatically serves static assets from your documentation repository at the appropriate path on your domain. For example, if you have `/images/my-logo.png` in your repo, the image file is available at `https://docs.your-project.com/images/my-logo.png`.
You can make any supported file type available to your users, including OpenAPI specifications, images, videos, and more.
Files must be less than 20 MB.
File serving is not supported for documentation sites with authentication enabled. If your site requires authentication, static files are not accessible at their direct URLs.
## Supported file types
Supported file types for all plans:
* **Images**: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.ico`
* **Video**: `.mp4`, `.webm`
* **Audio**: `.mp3`, `.wav`
* **Data**: `.json`, `.yaml`
* **Stylesheets**: `.css`
* **Scripts**: `.js`
* **Fonts**: `.woff`, `.woff2`, `.ttf`, `.eot`
Supported file types for Enterprise plans:
* **Documents**: `.pdf`, `.txt`
* **Data**: `.xml`, `.csv`
* **Archives**: `.zip`
## File organization
Organize your files using folders to keep your repository easy to navigate:
```text theme={null}
/your-project
|- docs.json
|- images/
|- logo.png
|- screenshots/
|- dashboard.png
|- assets/
|- whitepaper.pdf
|- demo-video.mp4
```
Files are served from the root of your domain, so the structure in your repository directly maps to the URL structure. From the previous example, `assets/whitepaper.pdf` would be available at `https://docs.your-project.com/assets/whitepaper.pdf`.
# Images and embeds
Source: https://www.mintlify.com/docs/create/image-embeds
Add images, embed YouTube videos, and include iframes in your MDX pages to enhance documentation with visual and interactive media content.
Add images, embed videos, and include interactive content with iframes to your documentation.
## Images
Add images to provide visual context, examples, or decoration to your documentation.
### Basic image syntax
Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add images to your documentation:
```mdx theme={null}
```
Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows.
Image files must be less than 20 MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com).
### HTML image embeds
For more control over image display, use HTML `` tags:
```jsx theme={null}
```
#### Resize images with inline styles
Use JSX inline styles with the `style` attribute to resize images:
```jsx theme={null}
```
#### Disable image zoom
To disable the default zoom on click for images, add the `noZoom` property:
```html highlight="4" theme={null}
```
#### Link images
To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
```html theme={null}
```
Images within anchor tags automatically display a pointer cursor to indicate they are clickable.
#### Light and dark mode images
To display different images for light and dark themes, use Tailwind CSS classes:
```html theme={null}
```
### SVG images
SVG files that use `foreignObject` elements render differently in production than in local development. Mintlify's image CDN strips `foreignObject` from SVGs as a security measure, which can truncate or hide text and other embedded HTML content.
This commonly affects SVGs exported from tools like [draw.io](https://www.drawio.com) that have HTML text formatting or word wrap turned on. To fix this, disable **Formatted Text** and **Word Wrap** on all labels in your diagram before exporting to SVG. See the [draw.io documentation](https://www.drawio.com/doc/faq/svg-export-text-problems) for more information on SVG exports.
## Videos
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.
Always include fallback text content within video elements for browsers that don't support video playback.
### YouTube embeds
Embed YouTube videos using iframe elements:
```html theme={null}
```
### Self-hosted videos
Use the HTML `
```
```mdx Frame with a caption theme={null}
Check out our redesigned dashboard with improved navigation.
```
#### Resize images with inline styles
Use JSX inline styles with the `style` attribute to resize images:
```jsx theme={null}
```
#### Disable image zoom
To disable the default zoom on click for images, add the `noZoom` property:
```html highlight="4" theme={null}
```
#### Link images
To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
```html theme={null}
```
```
### SVG images
SVG files that use `foreignObject` elements render differently in production than in local development. Mintlify's image CDN strips `foreignObject` from SVGs as a security measure, which can truncate or hide text and other embedded HTML content.
This commonly affects SVGs exported from tools like [draw.io](https://www.drawio.com) that have HTML text formatting or word wrap turned on. To fix this, disable **Formatted Text** and **Word Wrap** on all labels in your diagram before exporting to SVG. See the [draw.io documentation](https://www.drawio.com/doc/faq/svg-export-text-problems) for more information on SVG exports.
## Videos
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.