# AI-native
Source: https://mintlify.com/docs/ai-native
Learn how AI enhances reading, writing, and discovering your documentation
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-reference/assistant/create-assistant-message) to extend where users can access your documentation.
### Writing
The [agent](/ai/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-reference/agent/create-agent-job).
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 are sent 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 `llms-full.txt` files for your documentation. These industry-standard files help LLMs index your documentation and respond efficiently with relevant information to user queries.
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.
Add the agent to your Slack workspace or embed it into custom apps to have it help write and update your documentation.
Add a menu to pages that lets users query AI tools, connect to your MCP server, and copy pages as context with one click.
Your site has a hosted MCP server that lets users connect your documentation directly to their AI tools. Make your users aware of your MCP server and how to connect to it.
# Agent
Source: https://mintlify.com/docs/ai/agent
Automate documentation updates with the agent. Create pull requests from Slack messages, PRs, or API calls.
The agent is available on [Pro and Custom plans](https://mintlify.com/pricing?ref=agent) for anyone with access to your dashboard.
The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API.
Use the agent to:
* Write new content based on your prompts, links to pull requests, or Slack threads
* Revise outdated code examples and API references
* Search and update existing content
* Answer questions about your docs and technical writing topics
To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel.
## Add the agent to your Slack workspace
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.
1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard.
2. Select the **Connect** button.
3. Follow the Slack prompts to add the `mintlify` app to 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 it.
* Mention it with `@mintlify` in a channel.
## Connect repositories as context
The agent can only access repositories that you connect through the Mintlify GitHub App. Modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
## Embed the agent via API
Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs).
## Write effective prompts
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 your 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. For example:
* `@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 general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. For example:
* `@mintlify Find and fix all typos in the docs`
* `@mintlify change all unordered lists to use * instead of -`
## Specify a domain name
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.
Examples:
* `@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.
## Agent workflows
The agent assists with many different documentation tasks. These workflows 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]`.
### 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`.
### 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 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.
Learn how in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.
# Assistant
Source: https://mintlify.com/docs/ai/assistant
Add AI-powered chat to your docs that answers questions, cites sources, and generates code examples.
The assistant is automatically enabled on [Pro and Custom plans](https://mintlify.com/pricing?ref=assistant).
## About the assistant
The assistant answers questions about your documentation through natural language queries. It is embedded directly in your documentation site, so users can find answers quickly and succeed with your product.
The assistant uses agentic RAG (retrieval-augmented generation) with tool calling powered by Claude Opus 4.5. When users ask questions, the assistant:
* **Searches and retrieves** relevant content from your documentation to provide accurate answers.
* **Cites sources** and provides navigable links to take users directly to referenced pages.
* **Generates copyable code examples** to help users implement solutions from your documentation.
Each message sent to the assistant counts toward your plan's message allowance. If you exceed your allowance, additional messages incur overage charges. You can set spending limits or disable the assistant if you reach your message allowance.
You can view assistant usage through your dashboard to understand user behavior and documentation effectiveness. Export and analyze query data to help identify:
* Frequently asked questions that might need better coverage.
* Content gaps where users struggle to find answers.
* Popular topics that could benefit from additional content.
## Configure the assistant
The assistant is enabled by default for Pro and Custom plans.
Manage the assistant from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings). Click **Configuration** to enable or disable the assistant, configure response handling, add default questions, and set a spend limit.
### Enable or disable the assistant
Toggle the assistant status to enable or disable the assistant for your documentation site.
### Control placement
Select where the assistant appears on your documentation site. Choose between a floating chat bubble at the bottom of the page or a button next to the search bar.
### Set deflection email
In the response handling section, enable the assistant to redirect unanswered questions to your support team. Specify an email address that the assistant provides to users who ask questions that it cannot answer.
### Search sites
Site search is in beta. To enable it for your documentation site, [contact our sales team](mailto:gtm@mintlify.com).
In the response handling section, configure sites that the assistant can search for additional context when answering questions.
* Sites must be publicly available.
* Sites that require JavaScript to load are not supported.
Use the following filtering syntax for more precise control over what the assistant can search:
* **Domain-level filtering**
* `example.com`: Search only the `example.com` domain
* `docs.example.com`: Search only the `docs.example.com` subdomain
* `*.example.com`: Search all subdomains of `example.com`
* **Path-level filtering**
* `docs.example.com/api`: Search all pages under the `/api` subpath
* **Multiple patterns**
* Add multiple entries to target different sections of sites
### Add sample questions
Help your users start questions with the assistant by adding sample questions. In the search suggestions section, add up to three sample questions.
### Set a spend limit
Set a spend limit to control what happens if you reach your message allowance. By default, the assistant continues to answer user questions after you reach your message allowance, which incurs overages.
When you reach your spend limit, the assistant is disabled until your message allowance resets.
1. Select the **Billing** tab.
2. Set a spend limit for assistant messages beyond your allowance.
3. Set usage alerts to receive an email when you reach a certain percentage of your spend limit.
## Use the assistant
Users have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. Users can ask any question and the assistant searches your documentation for an answer. If no relevant information is found, the assistant responds that it cannot answer the question.
### UI placement
Depending on how you configure your assistant placement, the assistant appears as either a button next to the search bar or a bar at the bottom of the page.
### Keyboard shortcut
Open the assistant chat panel with the keyboard shortcut Command + I on macOS and Ctrl + I on Windows.
### Highlight text
Highlight text on a page and click the **Add to assistant** pop up button to open the assistant chat panel and add the highlighted text as context. You can add multiple text snippets or code blocks to the assistant's context.
### Code blocks
Click the **Ask AI** button in a code block to open the assistant chat panel and add the code block as context. You can add multiple code blocks or text snippets to the assistant's context.
### URLs
Append `?assistant=open` to a URL to open the assistant when the page loads. For example, [https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open).
## Making content AI ingestible
Structure your documentation to help the assistant provide accurate, relevant answers. Clear organization and comprehensive context benefit both human readers and AI understanding.
* Use semantic markup.
* Write descriptive headings for sections.
* Create a logical information hierarchy.
* Use consistent formatting across your docs.
* Include comprehensive metadata in page frontmatter.
* Break up long blocks of text into shorter paragraphs.
* Define specific terms and acronyms when first introduced.
* Provide sufficient conceptual content about features and procedures.
* Include examples and use cases.
* Cross-reference related topics.
* Add [hidden pages](/organize/hidden-pages) with additional context that users don't need, but the assistant can reference.
## Exporting and analyzing queries
Review and export queries from your dashboard to understand how people interact with your documentation and identify improvement opportunities. Some ways that analyzing queries can help you improve your documentation:
* Identify content gaps where frequent queries receive insufficient answers.
* Discover user behavior patterns and common information needs from themes and patterns in queries.
* Prioritize high-traffic pages for accuracy and quality improvements.
You can explore queries from your [dashboard](https://dashboard.mintlify.com/products/assistant), but to get more powerful insights we recommend exporting a `CSV` file of your queries, responses, and sources to analyze with your preferred AI tool.
1. Navigate to the [assistant page](https://dashboard.mintlify.com/products/assistant) in your dashboard.
2. Select **Export to CSV**.
3. Analyze the exported data using your preferred tool.
* Summarize the most common themes of the queries.
* List any queries that had no sources cited.
* Find patterns in unsuccessful interactions.
## Assistant insights
Use assistant insights to understand how users interact with your documentation through two views: categories and chat history.
### Categories
The categories tab uses LLMs to automatically categorize conversations by question topic and theme. Conversations are organized by the most common groupings, helping you quickly identify:
* Which topics generate the most questions
* Patterns in user needs and behavior
* Areas where documentation might need expansion or clarification
Review categories to see what areas of your documentation people frequently ask about and check that you have sufficient coverage of those topics.
### Chat history
The chat history tab displays chronological records of all assistant conversations. Select any message to view the complete chat thread, including the user's question, the assistant's response, and any sources cited.
## Troubleshooting
If the assistant UI is not visible in specific browsers, you may need to submit a false positive report to [EasyList](https://easylist.to). Browsers that use the EasyList Cookies List like Brave and Comet sometimes block the assistant or other UI elements. The EasyList Cookies List includes a domain-specific rule that hides fixed elements on certain domains to block cookie banners. This rule inadvertently affects legitimate UI components.
Submit a false positive report to [EasyList](https://github.com/easylist/easylist) to request removal of the rule. This resolves the issue for all users once the filter list is updated.
# Contextual menu
Source: https://mintlify.com/docs/ai/contextual-menu
Add one-click AI integrations to your docs.
export const PreviewButton = ({children, href}) => {
return
{children}
;
};
The contextual menu provides quick access to AI-optimized content and direct integrations with popular AI tools. When users select the contextual menu on any page, they can copy content as context for AI tools or open conversations in ChatGPT, Claude, Perplexity, or a custom tool of your choice with your documentation already loaded as context.
## Menu options
The contextual menu includes several pre-built options that you can enable by adding their identifier to your configuration.
| Option | Identifier | Description |
| :---------------------- | :----------- | :----------------------------------------------------------------------- |
| **Copy page** | `copy` | Copies the current page as Markdown for pasting as context into AI tools |
| **View as Markdown** | `view` | Opens the current page as Markdown |
| **Open in ChatGPT** | `chatgpt` | Creates a ChatGPT conversation with the current page as context |
| **Open in Claude** | `claude` | Creates a Claude conversation with the current page as context |
| **Open in Perplexity** | `perplexity` | Creates a Perplexity conversation with the current page as context |
| **Copy MCP server URL** | `mcp` | Copies your MCP server URL to the clipboard |
| **Connect to Cursor** | `cursor` | Installs your hosted MCP server in Cursor |
| **Connect to VS Code** | `vscode` | Installs your hosted MCP server in VS Code |
| **Custom options** | Object | Add custom options to the contextual menu |
## Enabling the contextual menu
Add the `contextual` field to your `docs.json` file and specify which options you want to include.
```json theme={null}
{
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"perplexity",
"mcp",
"cursor",
"vscode"
]
}
}
```
## Adding custom options
Create custom options in the contextual menu by adding an object to the `options` array. Each custom option requires these properties:
The title of the option.
The description of the option. Displayed beneath the title when the contextual menu is expanded.
The icon to display.
Options:
* [Font Awesome icon](https://fontawesome.com/icons) name
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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 href of the option. Use a string for simple links or an object for dynamic links with query parameters.
The base URL for the option.
The query parameters for the option.
The query parameter key.
The query parameter value. We will replace the following placeholders with the corresponding values:
* Use `$page` to insert the current page content in Markdown.
* Use `$path` to insert the current page path.
* Use `$mcp` to insert the hosted MCP server URL.
Example custom option:
```json {9-14} wrap theme={null}
{
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"perplexity",
{
"title": "Request a feature",
"description": "Join the discussion on GitHub to request a new feature",
"icon": "plus",
"href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests"
}
]
}
}
```
### Custom option examples
```json theme={null}
{
"title": "Request a feature",
"description": "Join the discussion on GitHub",
"icon": "plus",
"href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests"
}
```
```json theme={null}
{
"title": "Share on X",
"description": "Share this page on X",
"icon": "x",
"href": {
"base": "https://x.com/intent/tweet",
"query": [
{
"key": "text",
"value": "Check out this documentation: $page"
}
]
}
}
```
# llms.txt
Source: https://mintlify.com/docs/ai/llmstxt
Optimize your docs for LLMs to read and index.
export const PreviewButton = ({children, href}) => {
return
{children}
;
};
The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines. AI tools can use this file to understand your documentation structure and find content relevant to user queries.
Mintlify automatically hosts an `llms.txt` file at the root of your project that lists all available pages in your documentation. This file is always up to date and requires zero maintenance. You can optionally add a custom `llms.txt` file to the root of your project.
View your `llms.txt` by appending `/llms.txt` to your documentation site's URL.
Open the llms.txt for this site.
## llms.txt structure
An `llms.txt` file is a plain Markdown file that contains:
* **Site title** as an H1 heading.
* **Structured content sections** with links and a description of each page in your documentation.
Pages are listed alphabetically in the order they appear in your repository, starting from the root directory.
Each page's description comes from the `description` field in its frontmatter. Pages without a `description` field appear in the `llms.txt` file without a description.
```mdx Example llms.txt theme={null}
# Site title
## Docs
- [API](https://example.com/docs/api): Endpoint list and usage
- [Install](https://example.com/docs/install): Setup steps
- [Getting started](https://example.com/docs/start): Intro guide
```
This structured approach allows LLMs to efficiently process your documentation at a high level and locate relevant content for user queries, improving the accuracy and speed of AI-assisted documentation searches.
## llms-full.txt
The `llms-full.txt` file combines your entire documentation site into a single file as context for AI tools and is indexed by LLM traffic.
Mintlify automatically hosts an `llms-full.txt` file at the root of your project. View your `llms-full.txt` by appending `/llms-full.txt` to your documentation site's URL.
Open the llms-full.txt for this site.
## Custom files
To add a custom `llms.txt` or `llms-full.txt` file, create an `llms.txt` or `llms-full.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.
Your custom `llms.txt` or `llms-full.txt` file must have a site title as an H1 heading. Other content is optional. See [Format](https://llmstxt.org/#format) in the `llms.txt` specification for more information on optional sections and best practices.
# Markdown export
Source: https://mintlify.com/docs/ai/markdown-export
Quickly get Markdown versions of pages for AI tools and integrations.
export const PreviewButton = ({children, href}) => {
return
{children}
;
};
Markdown provides structured text that AI tools can process more efficiently than HTML, which results in better response accuracy, faster processing times, and lower token usage.
Mintlify automatically generates Markdown versions of pages that are optimized for AI tools and external integrations.
## .md URL extension
Add `.md` to any page's URL to view a Markdown version.
Open this page as Markdown
## Keyboard shortcut
Press Command + C (Ctrl + C on Windows) to copy a page as Markdown to your clipboard.
# Model Context Protocol
Source: https://mintlify.com/docs/ai/model-context-protocol
Connect your documentation and API endpoints to AI tools with a hosted MCP server.
export const PreviewButton = ({children, href}) => {
return
{children}
;
};
## About MCP servers
The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates an MCP server from your documentation and OpenAPI specifications, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, Goose, and others) can connect to your documentation and APIs.
Your MCP server exposes tools for AI applications to search your documentation and interact with your APIs.
### How MCP servers work
When an MCP server is connected to an AI tool, the LLM can decide to use your documentation and API tools during response generation.
* The LLM can proactively search your documentation or call your API endpoints while generating a response, not just when explicitly asked.
* The LLM determines when to use tools based on the context of the conversation and the relevance of your documentation and APIs.
* Each tool call happens during the generation process, allowing the LLM to incorporate real-time information from your documentation and APIs into its response.
For example, if a user asks a coding question and the LLM determines that your API documentation is relevant, it can search your API documentation and include that information in the response without the user explicitly asking about your documentation.
## Accessing your MCP server
MCP servers can only be generated for public documentation. Documentation behind end-user authentication cannot be accessed for server generation.
Mintlify automatically generates an MCP server for your documentation and hosts it at your documentation URL with the `/mcp` path. For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`.
You can see and copy your MCP server URL in your [dashboard](https://dashboard.mintlify.com/products/mcp).
The `/mcp` path is reserved for hosted MCP servers and cannot be used for other navigation elements.
## Configuring your MCP server
All MCP servers include the `search` tool by default, which allows users to query information from your docs in other tools.
If you have a [Pro or Custom plan](https://mintlify.com/pricing?ref=mcp), you can expose endpoints from your OpenAPI specification as MCP tools.
To expose endpoints as MCP tools, use the `mcp` object within the `x-mint` extension at either the file or endpoint level. For example, the Mintlify MCP server includes tools to create assistant chats, get status updates, and trigger updates.
MCP servers follow a security-first approach where API endpoints are not exposed by default. You must explicitly enable endpoints to make them available as MCP tools. Only expose endpoints that are safe for public access through AI tools.
The MCP configuration for the endpoint.
Whether to expose the endpoint as an MCP tool. Takes precedence over the file-level configuration.
The name of the MCP tool.
The description of the MCP tool.
### File-level configuration
Enable MCP for all endpoints by default in an OpenAPI specification file and selectively exclude endpoints:
```json theme={null}
{
"openapi": "3.1.0",
"x-mint": {
"mcp": {
"enabled": true
}
},
// ...
"paths": {
"/api/v1/users": {
"get": {
"x-mint": {
"mcp": {
"enabled": false // Disables MCP for this endpoint
}
},
// ...
}
}
}
}
```
### Endpoint-level configuration
Enable MCP for specific endpoints:
```json theme={null}
{
"paths": {
"/api/v1/users": {
"get": {
"x-mint": {
"mcp": {
"enabled": true,
"name": "get-users",
"description": "Get a list of users"
},
// ...
}
}
},
"/api/v1/delete": {
"delete": {
// No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
// ...
}
}
}
}
```
## Using your MCP server
Your users must connect your MCP server to their preferred AI tools.
1. Make your MCP server URL publicly available.
2. Users copy your MCP server URL and add it to their tools.
3. Users access your documentation and API endpoints through their tools.
These are some of the ways you can help your users connect to your MCP server:
Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page of your documentation.
| Option | Identifier | Description |
| :---------------------- | :--------- | :-------------------------------------------------- |
| **Copy MCP server URL** | `mcp` | Copies your MCP server URL to the user's clipboard. |
| **Connect to Cursor** | `cursor` | Installs your MCP server in Cursor. |
| **Connect to VS Code** | `vscode` | Installs your MCP server in VS Code. |
Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL.
Create a guide for your users that includes your MCP server URL and the steps to connect it to Claude.
1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
2. Select **Add custom connector**.
3. Add your MCP server name and URL.
4. Select **Add**.
5. When using Claude, select the attachments button (the plus icon).
6. Select your MCP server.
See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL.
Create a guide for your users that includes your MCP server URL and the command to connect it to Claude Code.
```bash theme={null}
claude mcp add --transport http
```
See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL.
Create a guide for your users that includes your MCP server URL and the steps to connect it to Cursor.
1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette.
2. Search for "Open MCP settings".
3. Select **Add custom MCP**. This will open the `mcp.json` file.
4. In `mcp.json`, configure your server:
```json theme={null}
{
"mcpServers": {
"": {
"url": ""
}
}
}
```
See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
Navigate to your [dashboard](https://dashboard.mintlify.com/products/mcp) and find your MCP server URL.
Create a guide for your users that includes your MCP server URL and the steps to connect it to VS Code.
1. Create a `.vscode/mcp.json` file.
2. In `mcp.json`, configure your server:
```json theme={null}
{
"servers": {
"": {
"type": "http",
"url": ""
}
}
}
```
See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
### Example: Connecting to the Mintlify MCP server
Connect to the Mintlify MCP server to interact with the Mintlify API and search our documentation. This will give you more accurate answers about how to use Mintlify in your local environment and demonstrates how you can help your users connect to your MCP server.
At the top of this page, select the contextual menu and choose **Connect to Cursor** or **Connect to VS Code** to connect the Mintlify MCP server to the IDE of your choice.
To use the Mintlify MCP server with Claude:
1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
2. Select **Add custom connector**.
3. Add the Mintlify MCP server:
* Name: `Mintlify`
* URL: `https://mintlify.com/docs/mcp`
4. Select **Add**.
1. When using Claude, select the attachments button (the plus icon).
2. Select the Mintlify MCP server.
3. Ask Claude a question about Mintlify.
See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
To use the Mintlify MCP server with Claude Code, run the following command:
```bash theme={null}
claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp
```
Test the connection by running:
```bash theme={null}
claude mcp list
```
See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
Install in Cursor
To connect the Mintlify MCP server to Cursor, click the **Install in Cursor** button. Or to manually connect the MCP server, follow these steps:
1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette.
2. Search for "Open MCP settings".
3. Select **Add custom MCP**. This will open the `mcp.json` file.
In `mcp.json`, add:
```json theme={null}
{
"mcpServers": {
"Mintlify": {
"url": "https://mintlify.com/docs/mcp"
}
}
}
```
In Cursor's chat, ask "What tools do you have available?" Cursor should show the Mintlify MCP server as an available tool.
See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details.
Install in VS Code
To connect the Mintlify MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add:
```json theme={null}
{
"servers": {
"Mintlify": {
"type": "http",
"url": "https://mintlify.com/docs/mcp"
}
}
}
```
See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
## Authentication
When you enable an API endpoint for MCP, the server includes the authentication requirements defined in your OpenAPI `securitySchemes` and `securityRequirement`. Any keys are handled directly by the tool and not stored or processed by Mintlify.
If a user asks their AI tool to call a protected endpoint, the tool will request the necessary authentication credentials from the user at that moment.
## Monitoring your MCP server
You can view all available MCP tools in the **Available tools** section of the [MCP Server page](https://dashboard.mintlify.com/products/mcp) in your dashboard.
## Troubleshooting
If your MCP server only exposes the search tool despite having an OpenAPI specification:
1. Verify your OpenAPI specification is valid and accessible.
2. Ensure you've explicitly enabled MCP for specific endpoints using `x-mint.mcp.enabled: true`.
3. Check your deployment logs for OpenAPI processing errors.
If OpenAPI processing fails, the server continues with just the search tool to maintain functionality.
If users report authentication problems:
1. Check that your OpenAPI specification includes proper `securitySchemes` definitions.
2. Confirm that enabled endpoints work with the specified authentication methods.
If AI tools aren't using your API endpoints effectively:
1. Add detailed `summary` and `description` fields to your endpoints.
2. Ensure parameter names and descriptions are self-explanatory.
3. Use the MCP dashboard to verify how your endpoints appear as tools.
# Add SDK examples
Source: https://mintlify.com/docs/api-playground/adding-sdk-examples
Display SDK code samples in your API documentation.
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.
This property can be added to any request method and 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://mintlify.com/docs/api-playground/asyncapi-setup
Create websocket documentation with AsyncAPI specifications.
## 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 websockets, 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 websockets 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"
}
]
}
```
### 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, the files will be placed in the **api-reference** folder of the docs repo.
## 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://mintlify.com/docs/api-playground/complex-data-types
Describe APIs with flexible schemas, optional properties, and multiple data formats using `oneOf`, `anyOf`, and `allOf` keywords.
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 are displayed 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://mintlify.com/docs/api-playground/managing-page-visibility
Control which API endpoints appear in your documentation navigation.
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 will 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://mintlify.com/docs/api-playground/mdx-setup
Document API endpoints manually with MDX files.
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 theme={null}
"api": {
"mdx": {
"server": "https://mintlify.com/api",
"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-configurations).
Create an MDX file for each endpoint. Define the `title` and `api` in the frontmatter:
```mdx theme={null}
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
```
Specify path parameters by wrapping them in `{}`:
```bash theme={null}
https://api.example.com/v1/endpoint/{userId}
```
If you have a `server` field configured in `docs.json`, you can use relative paths like `/v1/endpoint`.
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://mintlify.com/docs/api-playground/multiple-responses
Document multiple response variations for API endpoints.
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.
This property can be added to any response and 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
```
# OpenAPI setup
Source: https://mintlify.com/docs/api-playground/openapi-setup
Generate API pages from your OpenAPI specification automatically.
OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ 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 a valid OpenAPI specification in either JSON or YAML format that follows the [OpenAPI specification 3.0+](https://swagger.io/specification/).
You can reference multiple OpenAPI specifications to create pages for your API. Either organize sections for each specification in your navigation or reference specific endpoints from different specifications.
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 openapi-check `.
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.
## Customize your endpoint pages
Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension provides additional control over how your API documentation is generated and displayed.
### 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
}
]
}
}
}
}
```
### 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
Change the URL of the endpoint page in your docs using `x-mint: href`. When `x-mint: href` is present, the navigation entry links directly to the specified URL instead of generating an API page.
```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"
}
}
}
}
}
```
### MCP
Selectively expose endpoints as Model Context Protocol (MCP) tools by using `x-mint: mcp`. Only enable endpoints that are safe for public access through AI tools.
The MCP configuration for the endpoint.
Whether to expose the endpoint as an MCP tool. Takes precedence over the file-level configuration.
The name of the MCP tool.
The description of the MCP tool.
```json Selective enablement {6-9} wrap theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Create user",
"x-mint": {
"mcp": {
"enabled": true
},
// ...
}
}
},
"/users": {
"delete": {
"summary": "Delete user (admin only)",
// No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
// ...
}
}
}
}
```
```json Global enablement {3-5, 9-13} wrap theme={null}
{
"openapi": "3.1.0",
"x-mcp": {
"enabled": true // All endpoints are exposed as MCP tools by default
},
"paths": {
"/api/admin/delete": {
"delete": {
"x-mint": {
"mcp": {
"enabled": false // Disable MCP for this endpoint
}
},
"summary": "Delete resources"
}
}
}
}
```
For more information, see [Model Context Protocol](/ai/model-context-protocol).
## 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 file path in your docs repo or a URL to a hosted OpenAPI document.
Generated endpoint pages have these default metadata values:
* `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated 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 are included.
```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 generated API pages are stored 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
OpenAPI specifications are inherited down the navigation hierarchy. 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 file path in your reference. External OpenAPI URLs can be referenced 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 will 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. Webhooks are supported in OpenAPI 3.1+ documents.
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://mintlify.com/docs/api-playground/overview
Let developers test API endpoints directly in your documentation.
## Overview
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 openapi-check `.
```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.
Defaults to `interactive`.
Whether to pass API requests through a proxy server. Defaults to `true`.
Configurations for the autogenerated API examples.
Example languages for the autogenerated API snippets.
Languages display in the order specified.
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`.
### Example configuration
This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown 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
}
}
}
```
### 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
The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.
## Further reading
* [OpenAPI setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.
* [x-mint extension](/api-playground/openapi-setup#x-mint-extension) 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://mintlify.com/docs/api-playground/troubleshooting
Resolve common issues with API page configuration.
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 will pass 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 will 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#param-proxy). When using this configuration, you will need to configure CORS on your server since requests will 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 openapi-check ` 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 will appear in navigation. No other pages will be 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 will be 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.
# Accordions
Source: https://mintlify.com/docs/components/accordions
Use accordions to show and hide content.
Accordions allow users to expand and collapse content sections. Use accordions for progressive disclosure and to organize information.
## 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.
The icon to display.
Options:
* [Font Awesome icon](https://fontawesome.com/icons) name
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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://mintlify.com/docs/components/badge
Use badges to highlight status, labels, or metadata inline or standalone.
Use badges to display status indicators, labels, or metadata. Badges can be used inline within text or as standalone elements.
## Basic badge
Badge
```mdx theme={null}
Badge
```
## Colors
Badges support multiple color variants to convey different meanings.
BadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadge
```mdx theme={null}
BadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadgeBadge
```
## 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`, `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 icon](https://fontawesome.com/icons) name
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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://mintlify.com/docs/components/banner
Add a banner to display important site-wide announcements and 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 can be made 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
}
```
## Properties
The banner message. Supports plain text and Markdown formatting.
Whether users can dismiss the banner. When `true`, users can close the banner and it won't reappear for their session. Defaults to `false`.
# Callouts
Source: https://mintlify.com/docs/components/callouts
Use callouts to style and emphasize important content.
Callouts can be styled as a 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
```
# Cards
Source: https://mintlify.com/docs/components/cards
Highlight main points or links with customizable layouts and icons.
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.
```
## Grouping cards
Use the [Columns component](/components/columns) to organize multiple cards side by side.
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 icon](https://fontawesome.com/icons) name
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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://mintlify.com/docs/components/code-groups
Display multiple code examples in one component
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#styling) for configuration options.
## Creating 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://mintlify.com/docs/components/color
Display color palettes with click-to-copy functionality.
Use the Color component to showcase color palettes in your documentation. Colors can be displayed in a compact grid or organized 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://mintlify.com/docs/components/columns
Show elements side by side
The `Columns` component lets you group multiple `Card` components together. It's most often used to put cards in a grid, by specifying the number of grid columns.
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.
```
## Properties
The number of columns per row.
# Examples
Source: https://mintlify.com/docs/components/examples
Display code blocks in the right sidebar on desktop devices
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. These components are designed 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 and can be scrolled 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 pins 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" }
```
````
# Expandables
Source: https://mintlify.com/docs/components/expandables
Toggle to display nested properties
Use expandables to show and hide nested content within response fields. Expandables 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://mintlify.com/docs/components/fields
Document API request and response parameters with type information.
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://mintlify.com/docs/components/frames
Add visual emphasis with styled frames around images and other components.
Use frames to display images, diagrams, 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.
## Hints
Add text that precedes the frame using the optional `hint` prop. Hints appear above the frame.
## Properties
Text that appears as part of the frame, centered below the content.
Text that precedes the frame.
```mdx Frame theme={null}
```
```mdx Frame with a caption theme={null}
```
```mdx Frame with a hint theme={null}
```
```mdx Frame with both hint and caption theme={null}
```
# Icons
Source: https://mintlify.com/docs/components/icons
Use icons from popular libraries, external URLs, or files in your project.
Use icons from Font Awesome, Lucide, 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
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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 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.
# Mermaid
Source: https://mintlify.com/docs/components/mermaid-diagrams
Create flowcharts, diagrams, and visualizations with Mermaid syntax.
[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 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
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
```
````
## 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://mintlify.com/docs/components/panel
Customize the content of the right side panel on a page.
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#request-example) and [ResponseExample](/components/examples#response-example) components must be inside ``.
The components in a `` will 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.
# Response fields
Source: https://mintlify.com/docs/components/responses
Display API response values.
The `` component is designed 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://mintlify.com/docs/components/steps
Create numbered step-by-step procedures.
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`, and `h3`.
## Individual step properties
The content of a step either as plain text or components.
The icon to display.
Options:
* [Font Awesome icon](https://fontawesome.com/icons) name
* [Lucide icon](https://lucide.dev/icons) name
* JSX-compatible SVG code wrapped in curly braces
* URL to an externally hosted icon
* Path to an icon file in your project
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 title is the primary text for the step and shows up next to the indicator.
The number of the step.
The size of the step titles. One of `p`, `h2`, and `h3`.
# Tabs
Source: https://mintlify.com/docs/components/tabs
Organize content with tabs to show different options or versions.
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.
````
## Properties
The title of the tab. Short titles are easier to navigate.
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`.
# Tooltips
Source: https://mintlify.com/docs/components/tooltips
Add contextual help with hover tooltips for terms and concepts.
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.
The call-to-action text for a link within the tooltip.
URL for the call-to-action link. Required when using `cta`.
# Update
Source: https://mintlify.com/docs/components/update
Display product updates and changelog entries in a timeline format.
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).
## 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.
# View
Source: https://mintlify.com/docs/components/view
Create multi-view content for different programming languages or frameworks.
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.
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!")
```
````
## 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://mintlify.com/docs/create/changelogs
Create product changelogs with RSS feed support for subscribers.
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.
```
The table of contents and changelog filters are hidden when using `custom`, `center`, or `wide` page modes. Learn more about [page modes](/organize/pages#page-mode).
### Subscribable changelogs
Using `Update` components creates a subscribable RSS feed at your page URL with `/rss.xml` appended. For example, `mintlify.com/docs/changelog/rss.xml`.
Entries are added to the RSS feed when new `Update` components are published and when new headings are added inside of existing `` tags.
The top level headings of `Update` components are used as the titles of RSS feed entries, and the entries link to their heading anchors in your docs.
```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://mintlify.com/docs/create/code
Display and style inline code and code blocks.
## 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#param-styling) for configuration options.
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`
```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!");
}
}
```
````
### 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. Use `title="Your title"` or a string on a single line.
```javascript Title example theme={null}
const hello = "world";
```
````mdx Format theme={null}
```javascript Title example
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.
To create diffs, add these special comments at the end of lines in your code block:
* `// [!code ++]`: Mark a line as added (green highlight).
* `// [!code --]`: Mark a line as removed (red highlight).
For multiple consecutive lines, specify the number of lines after a colon:
* `// [!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.
The comment syntax must match your programming language (for example, `//` for JavaScript or `#` for Python).
```js Diff example lines theme={null}
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
````text Format theme={null}
```js Diff example lines
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
````
## 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://mintlify.com/docs/create/files
Serve static assets from your documentation.
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 for images and 100 MB for other file types.
File serving is not supported for documentation sites with authentication enabled. If your site requires authentication, static files will not be accessible at their direct URLs.
## Supported file types
### Image formats
* `.jpeg`, `.jpg`, `.jfif`, `.pjpeg`, `.pjp`
* `.png`
* `.svg`, `.svgz`
* `.ico`
* `.webp`
* `.gif`, `.apng`
* `.avif`
* `.bmp`
* `.tiff`, `.tif`
### Video formats
* `.mp4`
* `.webm`
* `.ogg`
* `.avi`
* `.mov`
* `.wmv`
* `.flv`
* `.mkv`
* `.m4v`
### Audio formats
* `.mp3`
* `.wav`
* `.flac`
* `.aac`
* `.ogg`
* `.wma`
* `.m4a`
### Font formats
* `.woff`
* `.woff2`
* `.ttf`
* `.otf`
* `.eot`
### Document formats
Document formats are only available for Custom plans and are not supported when authentication is enabled.
* `.pdf`
* `.txt`
* `.doc`, `.docx`
* `.xls`, `.xlsx`
* `.ppt`, `.pptx`
* `.rtf`
* `.odt`, `.ods`, `.odp`
### Data formats
Data formats are only available for Custom plans and are not supported when authentication is enabled.
* `.csv`
* `.tsv`
* `.xml`
### Archive formats
Archive formats are only available for Custom plans and are not supported when authentication is enabled.
* `.zip`
* `.rar`
* `.7z`
* `.tar`
* `.gz`
* `.bz2`
## 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://mintlify.com/docs/create/image-embeds
Add images, videos, andiframes.
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 zoom functionality
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}
```
## 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 `
### Enable or disable the assistant
Toggle the assistant status to enable or disable the assistant for your documentation site.
### Control placement
Select where the assistant appears on your documentation site. Choose between a floating chat bubble at the bottom of the page or a button next to the search bar.
### Set deflection email
In the response handling section, enable the assistant to redirect unanswered questions to your support team. Specify an email address that the assistant provides to users who ask questions that it cannot answer.
### Search sites
Use the following filtering syntax for more precise control over what the assistant can search:
* **Domain-level filtering**
* `example.com`: Search only the `example.com` domain
* `docs.example.com`: Search only the `docs.example.com` subdomain
* `*.example.com`: Search all subdomains of `example.com`
* **Path-level filtering**
* `docs.example.com/api`: Search all pages under the `/api` subpath
* **Multiple patterns**
* Add multiple entries to target different sections of sites
### Add sample questions
Help your users start questions with the assistant by adding sample questions. In the search suggestions section, add up to three sample questions.
### Set a spend limit
Set a spend limit to control what happens if you reach your message allowance. By default, the assistant continues to answer user questions after you reach your message allowance, which incurs overages.
When you reach your spend limit, the assistant is disabled until your message allowance resets.
1. Select the **Billing** tab.
2. Set a spend limit for assistant messages beyond your allowance.
3. Set usage alerts to receive an email when you reach a certain percentage of your spend limit.
## Use the assistant
Users have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. Users can ask any question and the assistant searches your documentation for an answer. If no relevant information is found, the assistant responds that it cannot answer the question.
### UI placement
Depending on how you configure your assistant placement, the assistant appears as either a button next to the search bar or a bar at the bottom of the page.
### Code blocks
Click the **Ask AI** button in a code block to open the assistant chat panel and add the code block as context. You can add multiple code blocks or text snippets to the assistant's context.
### URLs
Append `?assistant=open` to a URL to open the assistant when the page loads. For example, [https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open).
## Making content AI ingestible
Structure your documentation to help the assistant provide accurate, relevant answers. Clear organization and comprehensive context benefit both human readers and AI understanding.
## Enabling the contextual menu
Add the `contextual` field to your `docs.json` file and specify which options you want to include.
```json theme={null}
{
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"perplexity",
"mcp",
"cursor",
"vscode"
]
}
}
```
## Adding custom options
Create custom options in the contextual menu by adding an object to the `options` array. Each custom option requires these properties:
## Troubleshooting
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
## Captions
Add additional context to an image using the optional `caption` prop. Captions appear in the frame below the image.
## Hints
Add text that precedes the frame using the optional `hint` prop. Hints appear above the frame.
```
```mdx Frame with a caption theme={null}
### Features
* Responsive design
* Anchor for each update
* Generated RSS feed entry for each update
### 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}
# Format code
Source: https://mintlify.com/docs/create/code
Display and style inline code and code blocks.
## 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.
## 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}
```
```
#### Resize images with inline styles
Use JSX inline styles with the `style` attribute to resize images:
```jsx theme={null}
```
#### Disable zoom functionality
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}
```
```
## Videos
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.