# Editor permissions
Source: https://mintlify.com/docs/advanced/dashboard/permissions
Allow more members of your team to update your docs
An editor has access to your dashboard and web editor.
Anyone can contribute to your documentation by working locally and pushing changes to your repository, but there are key differences in how changes get deployed:
* **Editor changes**: When an editor publishes through the web editor or merges a pull request into your docs repository, changes deploy to your live site automatically.
* **Non-editor changes**: When a non-editor merges a pull request into your repository, you must manually trigger a deployment from your dashboard for those changes to appear on your live site.
## Add editors
By default, the team member who created your Mintlify organization has editor access. Add additional editors in the [Members](https://dashboard.mintlify.com/settings/organization/members) page of your dashboard.
Editor seats are billed based on usage, and you can have as many editors as you need. See our [pricing page](https://mintlify.com/pricing) for more details.
# Roles
Source: https://mintlify.com/docs/advanced/dashboard/roles
Control access to your dashboard with roles.
RBAC functionality is available on [Enterprise plan](https://mintlify.com/pricing?ref=rbac).
Mintlify provides two dashboard access levels: Editor and Admin.
The following describes actions that are limited to the Admin role:
| | Editor | Admin |
| ----------------------- | :----: | :---: |
| Update user roles | ❌ | ✅ |
| Delete users | ❌ | ✅ |
| Invite admin users | ❌ | ✅ |
| Manage & update billing | ❌ | ✅ |
| Update custom domain | ❌ | ✅ |
| Update Git source | ❌ | ✅ |
| Delete org | ❌ | ✅ |
Other actions on the dashboard are available to both roles.
You can invite as many admins as you want, but we recommend limiting admin
access to users who need it.
# Single sign-on (SSO)
Source: https://mintlify.com/docs/advanced/dashboard/sso
Customize how your team can login to your admin dashboard
SSO functionality is available on [Enterprise plan](https://mintlify.com/pricing?ref=sso).
Use single sign-on to your dashboard via SAML and OIDC. If you use Okta, Google Workspace, or Microsoft Entra, we have provider-specific documentation for setting up SSO. If you use another provider, please [contact us](mailto:support@mintlify.com).
## Okta
Under `Applications`, click to create a new app integration using SAML 2.0.
Enter the following:
* Single sign-on URL (provided by Mintlify)
* Audience URI (provided by Mintlify)
* Name ID Format: `EmailAddress`
* Attribute Statements:
| Name | Name format | Value |
| ----------- | ----------- | ---------------- |
| `firstName` | Basic | `user.firstName` |
| `lastName` | Basic | `user.lastName` |
Once the application is set up, navigate to the sign-on tab and send us the metadata URL.
We'll enable the connection from our side using this information.
Under `Applications`, click to create a new app integration using OIDC.
You should choose the `Web Application` application type.
Select the authorization code grant type and enter the Redirect URI provided by Mintlify.
Once the application is set up, navigate to the General tab and locate the client ID & client secret.
Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely.
## Google Workspace
Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown.
Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.
On the Service provider details page, enter the following:
* ACS URL (provided by Mintlify)
* Entity ID (provided by Mintlify)
* Name ID format: `EMAIL`
* Name ID: `Basic Information > Primary email`
On the next page, enter the following attribute statements:
| Google Directory Attribute | App Attribute |
| -------------------------- | ------------- |
| `First name` | `firstName` |
| `Last name` | `lastName` |
Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account!
## Microsoft Entra
1. Under "Enterprise applications", select **New application**.
2. Select **Create your own application** and choose "Integrate any other application you don't find in the gallery (Non-gallery)."
Navigate to the Single Sign-On setup page and select **SAML**. Under "Basic SAML Configuration," enter the following:
* Identifier (Entity ID): The Audience URI provided by Mintlify.
* Reply URL (Assertion Consumer Service URL): The ACS URL provided by Mintlify.
Leave the other values blank and select **Save**.
Edit the Attributes & Claims section:
1. Select **Unique User Identifier (Name ID)** under "Required Claim."
2. Change the Source attribute to use `user.primaryauthoritativeemail`.
3. Under Additional claims, create the following claims:
| Name | Value |
| ----------- | ---------------- |
| `firstName` | `user.givenname` |
| `lastName` | `user.surname` |
Once the application is set up, navigate to the "SAML Certificates" section and send us the App Federation Metadata URL.
We'll enable the connection from our side using this information.
Navigate to "Users and groups" in your Entra application and add the users who should have access to your dashboard.
# Cloudflare
Source: https://mintlify.com/docs/advanced/subpath/cloudflare
Host documentation at a custom subpath using Cloudflare Workers
To host your documentation at a custom subpath such as `yoursite.com/docs` using Cloudflare, you will need to create and configure a Cloudflare Worker.
Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare).
## Repository structure
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
## Set up a Cloudflare Worker
Create a Cloudflare Worker by following the [Cloudflare Workers getting started guide](https://developers.cloudflare.com/workers/get-started/dashboard/), if you have not already.
If your DNS provider is Cloudflare, do not use proxying for the CNAME record.
### Proxies with Vercel deployments
If you use Cloudflare as a proxy with Vercel deployments, you must ensure proper configuration to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
#### Required path allowlist
Your Cloudflare Worker must allow traffic to these specific paths without blocking or redirecting:
* `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
* `/.well-known/vercel/*` - Required for Vercel domain verification
While Cloudflare automatically handles many verification rules, creating additional custom rules may inadvertently block this critical traffic.
#### Header forwarding requirements
Ensure that the `HOST` header is correctly forwarded in your Worker configuration. Failure to properly forward headers will cause verification requests to fail.
### Configure routing
In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker's code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker.
Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, and `/docs` with your desired subpath if different.
```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// If the request is to a Vercel verification path, allow it to pass through
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// If the request is to the docs subdirectory
if (/^\/docs/.test(urlObject.pathname)) {
// Then Proxy to Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// If deploying to Vercel, preserve client IP
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
} catch (error) {
// If no action found, play the regular request
return await fetch(request);
}
}
```
Select **Deploy** and wait for the changes to propagate.
After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting.
### Test your Worker
After your code deploys, test your Worker to ensure it routes to your Mintlify docs.
1. Test using the Worker's preview URL: `your-worker.your-subdomain.workers.dev/docs`
2. Verify the Worker routes to your Mintlify docs and your website.
### Add custom domain
1. In your [Cloudflare dashboard](https://dash.cloudflare.com/), navigate to your Worker.
2. Go to **Settings > Domains & Routes > Add > Custom Domain**.
3. Add your domain.
We recommend you add your domain both with and without `www.` prepended.
See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information.
### Resolve DNS conflicts
If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must be configured to control all traffic for your domain.
1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information.
2. Return to your Worker and add your custom domain.
## Webflow custom routing
If you use Webflow to host your main site and want to serve Mintlify docs at `/docs` on the same domain, you'll need to configure custom routing through Cloudflare Workers to proxy all non-docs traffic to your main site.
Make sure your main site is set up on a landing page before deploying this Worker, or visitors to your main site will see errors.
1. In Webflow, set up a landing page for your main site like `landing.yoursite.com`. This will be the page that visitors see when they visit your site.
2. Deploy your main site to the landing page. This ensures that your main site remains accessible while you configure the Worker.
3. To avoid conflicts, update any absolute URLs in your main site to be relative.
4. In Cloudflare, select **Edit Code** and add the following script into your Worker's code.
Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website's base URL, `[LANDING_DOMAIN]` with your landing page URL, and `/docs` with your desired subpath if different.
```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
try {
const urlObject = new URL(request.url);
// If the request is to a Vercel verification path, allow it to pass through
if (urlObject.pathname.startsWith('/.well-known/')) {
return await fetch(request);
}
// If the request is to the docs subdirectory
if (/^\/docs/.test(urlObject.pathname)) {
// Proxy to Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
const CUSTOM_URL = "[YOUR_DOMAIN]";
let url = new URL(request.url);
url.hostname = DOCS_URL;
let proxyRequest = new Request(url, request);
proxyRequest.headers.set("Host", DOCS_URL);
proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
proxyRequest.headers.set("X-Forwarded-Proto", "https");
// If deploying to Vercel, preserve client IP
proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
return await fetch(proxyRequest);
}
// Route everything else to main site
const MAIN_SITE_URL = "[LANDING_DOMAIN]";
if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") {
let mainSiteUrl = new URL(request.url);
mainSiteUrl.hostname = MAIN_SITE_URL;
return await fetch(mainSiteUrl, {
method: request.method,
headers: request.headers,
body: request.body
});
}
} catch (error) {
// If no action found, serve the regular request
return await fetch(request);
}
}
```
5. Select **Deploy** and wait for the changes to propagate.
After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting.
# AWS Route 53 and CloudFront
Source: https://mintlify.com/docs/advanced/subpath/route53-cloudfront
Host documentation at a custom subpath using AWS services
To host your documentation at a custom subpath such as `yoursite.com/docs` using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.
## Repository structure
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
## High-level overview
Route traffic to these paths with a Cache Policy of **CachingDisabled**:
* `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
* `/.well-known/vercel/*` - Required for domain verification
* `/docs/*` - Required for subpath routing
* `/docs/` - Required for subpath routing
Route traffic to this path with a Cache Policy of **CachingEnabled**:
* `/mintlify-assets/_next/static/*`
* `Default (*)` - Your websites landing page
All Behaviors must have the an **origin request policy** of `AllViewerExceptHostHeader`.
## Create CloudFront distribution
1. Navigate to [CloudFront](https://aws.amazon.com/cloudfront) inside the AWS console.
2. Select **Create distribution**.
3. For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is your project's unique subdomain.
4. For "Web Application Firewall (WAF)," enable security protections.
5. The remaining settings should be default.
6. Select **Create distribution**.
## Add default origin
1. After creating the distribution, navigate to the "Origins" tab.
2. Find your staging URL that mirrors the main domain. This is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app).
If your landing page is hosted on Webflow, use Webflow's staging URL. It would look like `.webflow.io`.
If you use Vercel, use the `.vercel.app` domain available for every project.
3. Create a new Origin and add your staging URL as the "Origin domain".
By this point, you should have two Origins: one with `[SUBDOMAIN].mintlify.app` and another with your staging URL.
## Set behaviors
Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic:
* **If a user lands on your custom subpath**, go to `[SUBDOMAIN].mintlify.dev`.
* **If a user lands on any other page**, go the current landing page.
1. Navigate to the "Behaviors" tab of your CloudFront distribution.
2. Select the **Create behavior** button and create the following behaviors.
### `/.well-known/*`
Create behaviors for Vercel domain verification paths with a **Path pattern** of `/.well-known/*` and set **Origin and origin groups** to your docs URL.
For "Cache policy", select **CachingDisabled** to ensure these verification requests pass through without caching.
If `.well-known/*` is too generic, it can be narrowed down to 2 behaviors at a minimum for Vercel:
* `/.well-known/vercel/*` - Required for Vercel domain verification
* `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
### Your custom subpath
Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`).
* Set "Cache policy" to **CachingOptimized**.
* Set "Origin request policy" to **AllViewerExceptHostHeader**.
* Set Viewer Protocol Policy to **Redirect HTTP to HTTPS**
### Your custom subpath with wildcard
Create a behavior with a **Path pattern** of your chosen subpath followed by `/*`, for example `/docs/*`, and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
These settings should exactly match your base subpath behavior. With the exception of the **Path pattern**.
* Set "Cache policy" to **CachingOptimized**.
* Set "Origin request policy" to **AllViewerExceptHostHeader**.
* Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**
### `/mintlify-assets/_next/static/*`
* Set "Cache policy" to **CachingOptimized**
* Set "Origin request policy" to **AllViewerExceptHostHeader**
* Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**
### `Default (*)`
Lastly, we're going to edit the `Default (*)` behavior.
1. Change the default behavior's **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`).
2. Select **Save changes**.
### Check behaviors are set up correctly
If you follow the above steps, your behaviors should look like this:
## Preview distribution
You can now test if your distribution is set up properly by going to the "General" tab and visiting the **Distribution domain name** URL.
All pages should be directing to your main landing page, but if you append your chosen subpath, for example `/docs`, to the URL, you should see it going to your Mintlify documentation instance.
## Connect with Route53
Now, we're going to bring the functionality of the CloudFront distribution into your primary domain.
For this section, you can also refer to AWS's official guide on [Configuring
Amazon Route 53 to route traffic to a CloudFront
distribution](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config)
1. Navigate to [Route53](https://aws.amazon.com/route53) inside the AWS console.
2. Navigate to the "Hosted zone" for your primary domain.
3. Select **Create record**.
4. Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option.
5. Select **Create records**.
You may need to remove the existing A record if one currently exists.
Your documentation is now live at your chosen subpath for your primary domain.
After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting.
# Vercel
Source: https://mintlify.com/docs/advanced/subpath/vercel
Host documentation at a custom subpath using Vercel
export const VercelJsonGenerator = () => {
const [subdomain, setSubdomain] = useState('[SUBDOMAIN]');
const [subdirectory, setSubdirectory] = useState('docs');
const vercelConfig = {
rewrites: [{
source: "/_mintlify/api/request",
destination: `https://${subdomain}.mintlify.app/_mintlify/api/request`
}, {
source: "/api/request",
destination: `https://${subdomain}.mintlify.app/_mintlify/api/request`
}, {
source: `/${subdirectory}`,
destination: `https://${subdomain}.mintlify.app`
}, {
source: `/${subdirectory}/llms.txt`,
destination: `https://${subdomain}.mintlify.app/llms.txt`
}, {
source: `/${subdirectory}/llms-full.txt`,
destination: `https://${subdomain}.mintlify.app/llms-full.txt`
}, {
source: `/${subdirectory}/sitemap.xml`,
destination: `https://${subdomain}.mintlify.app/sitemap.xml`
}, {
source: `/${subdirectory}/robots.txt`,
destination: `https://${subdomain}.mintlify.app/robots.txt`
}, {
source: `/${subdirectory}/:path*`,
destination: `https://${subdomain}.mintlify.app/${subdirectory}/:path*`
}, {
source: "/mintlify-assets/:path+",
destination: `https://${subdomain}.mintlify.app/mintlify-assets/:path+`
}]
};
const copyToClipboard = () => {
navigator.clipboard.writeText(JSON.stringify(vercelConfig, null, 2)).then(() => {
console.log('Copied config to clipboard!');
}).catch(err => {
console.error("Failed to copy: ", err);
});
};
return
;
};
## vercel.json file
The `vercel.json` file configures how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
We use the `rewrites` configuration to proxy requests from your main domain to your documentation.
Rewrites map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely.
You can customize the subpath to any value you prefer, such as `/docs`, `/help`, or `/guides`. Additionally, you can use deeply nested subpaths like `/product/docs`.
## Repository structure
Your documentation files must be organized within your repository to match your chosen subpath structure. For example, if you want your documentation at `yoursite.com/docs`, you would create a `docs/` directory with all of your documentation files.
## Configuration
To host your documentation at a custom subpath using Vercel, add the following configuration to your `vercel.json` file. This example uses `/docs`, but you can replace it with any subpath:
```json
{
"rewrites": [
{
"source": "/docs",
"destination": "https://[subdomain].mintlify.dev/docs"
},
{
"source": "/docs/:match*",
"destination": "https://[subdomain].mintlify.dev/docs/:match*"
}
]
}
```
* **`source`**: The path pattern on your domain that triggers the rewrite.
* **`destination`**: Where the request should be proxied to.
* **`:match*`**: A wildcard that captures any path segments after your subpath.
For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
### Generate rewrites
Enter your subdomain and custom subdirectory to generate the rewrites for your `vercel.json` file.
## Using external proxies with Vercel
If you're using an external proxy (like Cloudflare or AWS CloudFront) in front of your Vercel deployment, you must configure it properly to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
See the [supported providers](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) in the Vercel documentation.
### Required path allowlist
Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching:
* `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
* `/.well-known/vercel/*` - Required for Vercel domain verification
* `/mintlify-assets/_next/static/*` - Required for static assets
These paths should pass through directly to your Vercel deployment without modification.
### Header forwarding requirements
Ensure that your proxy correctly forwards the `HOST` header. Without proper header forwarding, verification requests will fail.
### Testing your proxy setup
To verify your proxy is correctly configured:
1. Test that `https://[yourdomain].com/.well-known/vercel/` returns a response.
2. Ensure SSL certificates are provisioning correctly in your Vercel dashboard.
3. Check that domain verification completes successfully.
# 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 |
## Enabling the contextual menu
Add the `contextual` field to your `docs.json` file and specify which options you want to include.
```json
{
"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
{
"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
{
"title": "Request a feature",
"description": "Join the discussion on GitHub",
"icon": "plus",
"href": "https://github.com/orgs/mintlify/discussions/categories/feature-requests"
}
```
```json
{
"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
Make your content easier 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.
```mdx Example llms.txt
# Example product docs
## Guides
- [Getting started](https://example.com/docs/start): Intro guide
- [Install](https://example.com/docs/install): Setup steps
## Reference
- [API](https://example.com/docs/api): Endpoint list and usage
```
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
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
Let users access your docs and APIs through their favorite AI tools
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.
## 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, allowing users to query information from your docs in other tools.
If you have a [Pro or Enterprise 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
{
"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
{
"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
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
{
"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
{
"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
claude mcp add --transport http Mintlify https://mintlify.com/docs/mcp
```
Test the connection by running:
```bash
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
{
"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
{
"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.
# Slack app
Source: https://mintlify.com/docs/ai/slack-app
Add a bot that searches your docs to answer questions in your Slack workspace
The Slack app is available for [Pro and Enterprise plans](https://mintlify.com/pricing?ref=slack-app).
The Slack app adds a bot named `@mintlify` to your Slack workspace that can search your documentation and answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`.
The Slack app can incur costs: either using your AI assistant credits or incurring overages.
## Setting up the Slack app
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify Slack app before you add it.
1. Navigate to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard.
2. Select **Connect** in the Slack Integration card.
3. Follow the Slack prompts to add the app to your workspace.
4. Test that the bot is working and responds when you:
* Send a direct message to the Mintlify app.
* Mention the bot with `@mintlify` in a channel.
* Create an `#ask-ai` channel, add the bot, and ask a question.
# Feedback
Source: https://mintlify.com/docs/analytics/feedback
Monitor user satisfaction with your documentation
To collect and view feedback, you must first enable feedback from the [Add-ons](https://dashboard.mintlify.com/products/addons) page in your dashboard.
The feedback tab displays quantitative thumbs up and thumbs down votes your docs have received and any qualitative feedback that users have provided. Use this information to gauge the quality of your docs and make improvements.
Access the feedback tab by navigating to the **Analytics** page in your [dashboard](https://dashboard.mintlify.com/products/analytics).
## Feedback types
Contextual and code snippet feedback are in beta. To enable them for your documentation site, [contact our sales team](mailto:gtm@mintlify.com).
The feedback tab displays information according to the feedback add-ons that you enable.
Enable your preferred feedback types:
* **Thumbs rating only**: Simple thumbs up/down voting to gauge overall satisfaction with pages.
* **Code snippet feedback only**: Feedback specifically on code snippets.
* **Thumbs rating and contextual feedback**: Page voting plus detailed comments and reasons for ratings.
* **Thumbs rating and code snippet feedback**: Page voting plus feedback on code examples.
* **Thumbs rating, contextual, and code snippet feedback**: Complete feedback system with page voting, detailed comments, and code snippet feedback.
## Managing feedback
For contextual and code snippet feedback, you can set the status of a piece of feedback and add internal notes to track your work resolving user feedback.
### Changing feedback status
Select the status beside a piece of feedback to mark it as **Pending**, **In Progress**, **Resolved**, or **Dismissed**.
Best practices for setting feedback statuses:
* **Pending**: Feedback is awaiting review.
* **In Progress**: Feedback has been validated and is being worked on.
* **Resolved**: Feedback has been resolved.
* **Dismissed**: Feedback has been dismissed as not actionable, irrelevant, or inaccurate.
### Filtering by status
Use the status filter to control which feedback is displayed. Uncheck a status to hide all feedback with that status. By default, all feedback is displayed.
### Adding internal notes
Click on a piece of feedback to add an internal note. These notes are only visible to people with access to your dashboard.
Use notes to add information for collaboration, link relevant support or engineering tickets, or remember any other useful information.
## Using feedback data
Review your feedback data to:
* **Identify successful content**: Pages with the most positive feedback show what works well in your documentation.
* **Prioritize improvements**: Pages with the most negative feedback indicate what content might need attention.
* **Take action**: Make documentation updates based on direct user feedback.
# Improving your docs
Source: https://mintlify.com/docs/analytics/improving-docs
Use analytics data to make your documentation better
Improve your docs based on quantitative and qualitative data from your analytics dashboard.
## Cross-analytics insights
Combine information from multiple analytics sources to get a holistic view of your documentation.
### Correlate traffic and satisfaction
* **High traffic and low feedback scores**: Popular pages with a poor user experience. Prioritize improving these pages.
* **Low traffic and high feedback scores**: Documentation that is working well, but might not be discoverable. Consider promoting these pages.
* **High traffic and high feedback scores**: Your documentation's greatest hits. Review these pages for ideas to improve the rest of your content.
### Match search intent with content performance
* **High search volume and low page views**: Discoverability problems. Consider moving these pages or reviewing their frontmatter.
* **Popular search terms and low-confidence results**: Content gap opportunity. Consider adding more content or new content on these topics.
* **Top searches and negative feedback on matching pages**: User experience issues. Review the pages to see if they solve the user need that is being searched for.
## Put insights into action
Use these cross-analytics patterns to prioritize your documentation improvements:
* **Fix high-impact problems first**: Popular pages with poor feedback scores affect the most users.
* **Fill verified content gaps**: Low-confidence searches with high volume indicate unmet user needs.
* **Respond to user feedback**: Contextual and code snippet feedback can identify specific areas for improvement.
* **Align search and content**: Ensure your most-searched topics have comprehensive, well-organized pages.
* **Monitor rising search trends with no existing popular pages**: New content opportunities.
# Overview
Source: https://mintlify.com/docs/analytics/overview
View traffic and high-level insights about your documentation
The overview tab shows how many people have visited your docs, what pages are most popular, and where users are coming from. Use this information to identify which pages are most valuable to your users and track trends over time.
Access the overview metrics by navigating to the **Analytics** page in your [dashboard](https://dashboard.mintlify.com/products/analytics).
## Metrics
Use the range selector to adjust the time period for displayed data. Select visitors, views, or actions to display a line graph showing trends over the selected time period.
* **Visitors**: Unique visitors
* **Views**: Total page views
* **Actions**: Combined count of API calls, navbar link clicks, and CTA button clicks
* **Popular Pages**: Paths to the most-visited pages and their view counts
* **Referrers**: Top traffic sources directing users to your docs
## Using overview data
Review your overview analytics to:
* **Identify popular pages**: Use popular pages to understand what content is most important to your users so that you can make sure it is up to date and comprehensive.
* **Track traffic trends**: Monitor changes in traffic to understand the impact of updates or new content.
# Search
Source: https://mintlify.com/docs/analytics/search
Understand how users search within your documentation
Use the data on the search tab to understand what users are searching for and identify topics that need to be updated or expanded.
Access your search metrics by navigating to the **Analytics** page in your [dashboard](https://dashboard.mintlify.com/products/analytics).
## Search metrics
Use the range selector to adjust the time period for displayed data.
* **Total queries**: Search volume
* **Top searches**: Most-searched terms
* **Low-confidence searches**: Queries that may not have returned relevant results
## Using search data
Review your search analytics to:
* **Identify popular topics**: Use top searches to understand what content people want to find.
* **Find content gaps**: Low-confidence searches may indicate missing documentation or topics that need better coverage.
* **Improve discoverability**: Ensure that pages matching popular search terms are easy to find and well-organized.
# Playground
Source: https://mintlify.com/docs/api-playground/asyncapi/playground
Enable users to interact with your websockets
# AsyncAPI setup
Source: https://mintlify.com/docs/api-playground/asyncapi/setup
Create websocket reference pages with AsyncAPI
## Add an AsyncAPI specification file
To begin to create pages for your websockets, make sure you have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0). Your schema must follow the AsyncAPI specification 3.0+.
To make sure your AsyncAPI schema is valid, you can paste it into the
[AsyncAPI Studio](https://studio.asyncapi.com/)
## Auto-populate websockets pages
You can add an `asyncapi` field to any tab or group in the navigation of your `docs.json`. This field can contain either the path to an AsyncAPI schema document in your docs repo, the URL of a hosted AsyncAPI schema document, or an array of links to AsyncAPI schema documents. Mintlify will automatically generate a page for each AsyncAPI websocket channel.
**Examples with Tabs:**
```json Local File {5}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "/path/to/asyncapi.json"
}
]
}
```
```json Remote URL {5}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
}
]
}
```
**Examples with Groups:**
```json {8-11}
"navigation": {
"tabs": [
{
"tab": "AsyncAPI",
"groups": [
{
"group": "Websockets",
"asyncapi": {
"source": "/path/to/asyncapi.json",
"directory": "api-reference"
}
}
]
}
]
}
```
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 just reference a single channel, you can create an MDX file with the `asyncapi` field in the frontmatter.
```mdx
---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---
```
# Adding SDK examples
Source: https://mintlify.com/docs/api-playground/customization/adding-sdk-examples
Display language-specific code samples alongside your API endpoints to show developers how to use your SDKs
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
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 });
```
# Complex data types
Source: https://mintlify.com/docs/api-playground/customization/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
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
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
# Managing page visibility
Source: https://mintlify.com/docs/api-playground/customization/managing-page-visibility
Control which endpoints from your OpenAPI specification appear in your documentation navigation
You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation.
If your pages are autogenerated from an OpenAPI document, you can 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 {11, 19}
"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 {9, 15}
"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!)"
}
}
}
```
# Multiple responses
Source: https://mintlify.com/docs/api-playground/customization/multiple-responses
Show response variations for the same endpoint
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
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
```
# Authentication
Source: https://mintlify.com/docs/api-playground/mdx/authentication
You can set authentication parameters to let users use their real API keys.
## Enabling authentication
You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis.
A page's authentication method will override a global method if both are set.
### Bearer token
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "bearer"
---
```
### Basic authentication
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "basic"
---
```
### API key
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "key"
---
```
### None
The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.
```mdx Page Metadata
---
title: "Your page title"
authMethod: "none"
---
```
# MDX setup
Source: https://mintlify.com/docs/api-playground/mdx/configuration
Generate docs pages for your API endpoints using `MDX`
You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most projects because it is more maintainable and feature-rich. However, creating `MDX` pages for an API can be useful to document small APIs or for prototyping.
To generate pages for API endpoints using `MDX`, configure your API settings in `docs.json`, create individual `MDX` files for each endpoint, and use components like `` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples.
In your `docs.json` file, define your base URL and auth method:
```json
"api": {
"mdx": {
"server": "https://mintlify.com/api", // string array for multiple base URLs
"auth": {
"method": "key",
"name": "x-api-key" // options: bearer, basic, key.
}
}
}
```
If you want to hide the API playground, use the `display` field. You do not need to include an auth method if you hide the playground.
```json
"api": {
"playground": {
"display": "none"
}
}
```
Find a full list of API configurations in [Settings](/settings#api-configurations).
Each API endpoint page should have a corresponding `MDX` file. At the top of each file, define `title` and `api`:
```mdx
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
```
You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
```bash
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`.
You can override the globally-defined display mode for the API playground for a page by adding `playground` to the frontmatter:
```mdx
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
```
* `playground: 'interactive'` - Display the interactive playground.
* `playground: 'simple'` - Display a copyable endpoint with no playground.
* `playground: 'none'` - Hide the playground.
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs in [Navigation](/navigation).
## Enabling authentication
You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis.
A page's authentication method will override a global method if both are set.
### Bearer token
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "bearer"
---
```
### Basic authentication
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "basic"
---
```
### API key
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
```mdx Page Metadata
---
title: "Your page title"
authMethod: "key"
---
```
### None
The `none` authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.
```mdx Page Metadata
---
title: "Your page title"
authMethod: "none"
---
```
# Migrating MDX API pages to OpenAPI navigation
Source: https://mintlify.com/docs/api-playground/migrating-from-mdx
Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation
If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation.
You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation.
## CLI migration
The `mint migrate-mdx` command is the recommended way to migrate from MDX endpoint pages to autogenerated pages.
This command:
* Parses your `docs.json` navigation structure.
* Identifies MDX pages that generate OpenAPI endpoint pages.
* Extracts content from MDX files and moves it to the `x-mint` extension in your OpenAPI specification.
* Updates your `docs.json` to reference the OpenAPI endpoints directly instead of MDX files.
* Deletes the original MDX endpoint files.
If you already have `x-mint` defined for an endpoint and also have an MDX page with content for that endpoint, the MDX content will overwrite existing `x-mint` settings.
If you have multiple MDX pages for the same endpoint with different content, the script will use the content from the page that appears last in your `docs.json`.
The migration tool does not support previewing changes before applying them.
Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
Any MDX pages you want to migrate must have the `openapi:` frontmatter referencing an endpoint.
Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
If needed, install or update the [Mint CLI](/installation).
```bash
mint migrate-mdx
```
## Manual migration steps
Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
For any endpoints that you want to customize the metadata or content, add the `x-mint` extension to the endpoint. See [x-mint extension](/api-playground/openapi-setup#x-mint-extension) for more details.
For any endpoints that you want to exclude from your documentation, add the `x-hidden` extension to the endpoint.
Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
```json
"navigation": {
"groups": [
{
"group": "API Reference",
"openapi": "/path/to/openapi.json",
"pages": [
"overview",
"authentication",
"introduction",
"GET /health",
"quickstart",
"POST /users",
"GET /users/{id}",
"advanced-features"
]
}
]
}
```
After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
## Navigation patterns
You can customize how your API documentation appears in your navigation.
### Mixed content navigation
Combine automatically generated API pages with other pages:
```json
"navigation": {
"groups": [
{
"group": "API Reference",
"openapi": "openapi.json",
"pages": [
"api/overview",
"GET /users",
"POST /users",
"api/authentication"
]
}
]
}
```
### Multiple API versions
Organize different API versions using tabs or groups:
```json
"navigation": {
"tabs": [
{
"tab": "API v1",
"openapi": "specs/v1.json"
},
{
"tab": "API v2",
"openapi": "specs/v2.json"
}
]
}
```
## When to use individual `MDX` pages
Consider keeping individual `MDX` pages when you need:
* Extensive custom content per endpoint like React components or lengthy examples.
* Unique page layouts.
* Experimental documentation approaches for specific endpoints.
For most use cases, OpenAPI navigation provides better maintainability and consistency.
# OpenAPI setup
Source: https://mintlify.com/docs/api-playground/openapi-setup
Reference OpenAPI endpoints in your docs pages
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 document in either JSON or YAML format that follows the [OpenAPI specification 3.0+](https://swagger.io/specification/).
You can create API pages from a single or multiple OpenAPI documents.
### Describing your API
We recommend the following resources to learn about and construct your OpenAPI documents.
* [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.
### Specifying the URL for your API
To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.
```json
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
In an OpenAPI document, 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 will allow users to toggle between servers. If you do not specify a server, the API playground will use 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 server field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.
### Specifying authentication
To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI document. The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document.
Add a `securitySchemes` field to define how users authenticate.
This example shows a configuration for bearer authentication.
```json
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Add a `security` field to require authentication.
```json
{
"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.
## `x-mint` extension
The `x-mint` extension is a custom OpenAPI extension that 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}
{
"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`:
```json {6-8}
{
"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
}
]
}
}
}
}
```
The `content` extension supports all Mintlify MDX components and formatting.
### Href
Change the URL of the endpoint page in your docs using `x-mint: href`:
```json {6-8, 14-16}
{
"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"
}
}
}
}
}
```
When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
### 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
{
"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
{
"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 will appear 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/customization/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 will be included:
```json {5}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
You can use multiple OpenAPI specifications in different navigation sections:
```json {8-11, 15-18}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
},
{
"group": "Admin",
"openapi": {
"source": "/path/to/openapi-2.json",
"directory": "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.
#### 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}
"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` will generate an API page for that endpoint using the default OpenAPI spec.
#### 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}
{
"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:
```json {5-6}
"navigation": {
"pages": [
"introduction",
"user-guides",
"/path/to/openapi-v1.json POST /users",
"/path/to/openapi-v2.json GET /orders"
]
}
```
This approach is useful when you need individual endpoints from different specs or only want to include select endpoints.
## Create `MDX` files for API pages
For control over individual endpoint pages, create `MDX` pages for each operation. This lets you customize page metadata, add content, omit certain operations, or reorder pages in your navigation at the page level.
See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases).
### Manually specify files
Create an `MDX` page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter.
When you reference an OpenAPI operation this way, the name, description, parameters, responses, and API playground are automatically generated from your OpenAPI document.
If you have multiple OpenAPI files, include the file path in your reference to ensure Mintlify finds the correct OpenAPI document. If you have only one OpenAPI file, Mintlify will detect it automatically.
This approach works regardless of whether you have set a default OpenAPI spec
in your navigation. You can reference any endpoint from any OpenAPI spec by
including the file path in the frontmatter.
If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
```mdx Example
---
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
---
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 the definition in your OpenAPI
specification. If the endpoint doesn't exist in the OpenAPI file, the page
will be empty.
### Autogenerate `MDX` files
Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.
Your OpenAPI document must be valid or the files will not autogenerate.
The scraper generates:
* An `MDX` page for each operation in the `paths` field of your OpenAPI document.
* If your OpenAPI document is version 3.1+, an `MDX` page for each operation in the `webhooks` field of your OpenAPI document.
* An array of navigation entries that you can add to your `docs.json`.
```bash
npx @mintlify/scraping@latest openapi-file
```
```bash
npx @mintlify/scraping@latest openapi-file -o api-reference
```
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.
### Create `MDX` files for OpenAPI schemas
You can create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schema` field:
```mdx Example
---
openapi-schema: OrderItem
---
```
```mdx Format
---
openapi-schema: "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.
### Define webhooks in your OpenAPI specification
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.
### Reference webhooks in MDX files
When creating MDX pages for webhooks, use `webhook` instead of HTTP methods like `GET` or `POST`:
```mdx
---
title: "Example webhook"
description: "Triggered when an event occurs"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
```
The webhook name must exactly match the key defined in your OpenAPI
specification's `webhooks` field.
# Playground
Source: https://mintlify.com/docs/api-playground/overview
Enable users to interact with your API
## 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.
The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.
## Getting started
Make sure that your OpenAPI specification file is valid using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
```bash {2}
/your-project
|- docs.json
|- openapi.json
```
Update your `docs.json` to reference your OpenAPI specification. Add an `openapi` property to any navigation element to auto-populate your docs with pages for each endpoint specified in your OpenAPI document.
This example generates a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
```json
"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 genereate other endpoint pages, add additional endpoints to the `pages` array.
```json
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
```
## Customizing your playground
You can 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`.
### Example configuration
```json
{
"api": {
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["curl", "python", "javascript"],
"defaults": "required"
}
}
}
```
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.
### 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.
For more information, see [x-mint extension](/api-playground/openapi-setup#x-mint-extension) and [MDX Setup](/api-playground/mdx/configuration).
## Further reading
* [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
Common issues with API References
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
---
openapi: "GET /users/{id}/"
---
```
```yaml openapi.yaml
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
---
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](/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}
"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.
# Assistant message
Source: https://mintlify.com/docs/api-reference/assistant/create-assistant-message
POST /assistant/{domain}/message
Generates a response message from the assistant for the specified domain.
## Rate limits
The assistant API has the following limits:
* 10,000 uses per key per month
* 10,000 requests per Mintlify organization per hour
* 10,000 requests per IP per day
## Suggested usage
For best results, use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses.
You can set `fp`, `threadId`, and `filter` in the `body` field of the options parameter passed to the hook.
# Search documentation
Source: https://mintlify.com/docs/api-reference/assistant/search
POST /search/{domain}
Perform semantic and keyword searches across your documentation with configurable filtering and pagination.
# Introduction
Source: https://mintlify.com/docs/api-reference/introduction
Trigger updates, embed AI assistant, and more
The Mintlify REST API enables you to programmatically interact with your documentation, trigger updates, and embed AI-powered chat experiences.
## Endpoints
* [Trigger update](/api-reference/update/trigger): Trigger an update of your site when desired.
* [Get update status](/api-reference/update/status): Get the status of an update and other details about your docs.
* [Generate assistant message](/api-reference/assistant/create-assistant-message): Embed the assistant, trained on your docs, into any application of your choosing.
* [Search documentation](/api-reference/assistant/search): Search through your documentation.
## Authentication
You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). API keys are associated with an entire organization and can be used across multiple deployments.
### Admin API key
The admin API key is used for the [Trigger update](/api-reference/update/trigger) and [Get update status](/api-reference/update/status) endpoints.
Admin API keys begin with the `mint_` prefix. Keep your admin API keys secret.
### Assistant API key
The assistant API key is used for the [Generate assistant message](/api-reference/assistant/create-assistant-message) and [Search documentation](/api-reference/assistant/search) endpoints.
Assistant API keys begin with the `mint_dsc_` prefix.
The assistant API **key** is a server-side token that should be kept secret.
The assistant API **token** is a public token that can be referenced in your frontend code.
Calls using the assistant API token can incur costs: either using your AI assistant credits or incurring overages.
# Get update status
Source: https://mintlify.com/docs/api-reference/update/status
GET /project/update-status/{statusId}
Get the status of an update from the status ID
# Trigger update
Source: https://mintlify.com/docs/api-reference/update/trigger
POST /project/update/{projectId}
Trigger an update after updating your OpenAPI document by calling this endpoint in a CI check
# Authentication setup
Source: https://mintlify.com/docs/authentication-personalization/authentication-setup
Control the privacy of your docs by authenticating users
[Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication.
[Enterprise plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods.
Authentication requires users to log in before accessing your documentation.
## Authentication modes
Choose between full and partial authentication modes based on your access control needs.
**Full authentication**: All pages are protected. Users must log in before accessing any content.
**Partial authentication**: Some pages are publicly viewable while others require authentication. Users can browse public content freely and authenticate only when accessing protected pages.
When configuring any handshake method below, you'll select either **Full authentication** or **Partial authentication** in your dashboard settings.
## Configuring authentication
Select the handshake method that you want to configure.
Password authentication provides access control only and does **not** support content personalization.
### Prerequisites
* Your security requirements allow sharing passwords among users.
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **Password**.
4. Enter a secure password.
5. Select **Save changes**.
Securely share the password and documentation URL with authorized users.
## Example
Your documentation is hosted at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.
**Create a strong password** in your dashboard. **Share credentials** with authorized users. That's it!
### Prerequisites
* Your documentation users are also your documentation editors.
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **Mintlify Auth**.
4. Select **Enable Mintlify Auth**.
1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members).
2. Add each person who should have access to your documentation.
3. Assign appropriate roles based on their editing permissions.
### Example
Your documentation is hosted at `docs.foo.com` and your team uses the dashboard to edit your docs. You want to restrict access to team members only.
**Enable Mintlify authentication** in your dashboard settings.
**Verify team access** by checking that all team members are added to your organization.
### Prerequisites
* An OAuth or OIDC server that supports the Authorization Code Flow.
* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features).
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **OAuth** and configure these fields:
* **Authorization URL**: Your OAuth endpoint.
* **Client ID**: Your OAuth 2.0 client identifier.
* **Client Secret**: Your OAuth 2.0 client secret.
* **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels.
* **Token URL**: Your OAuth token exchange endpoint.
* **Info API URL** (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty.
* **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL.
4. Select **Save changes**.
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
To enable personalization features, create an API endpoint that:
* Accepts OAuth access tokens for authentication.
* Returns user data in the `User` format. See [User data format](/authentication-personalization/personalization-setup#user-data-format) for more information.
Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
### Example
Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.
**Configure your OAuth server details** in your dashboard:
* **Authorization URL**: `https://auth.foo.com/authorization`
* **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
* **Scopes**: `['provider.users.docs']`
* **Token URL**: `https://auth.foo.com/exchange`
* **Info API URL**: `https://api.foo.com/docs/user-info`
* **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`
**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope, and returns:
```json
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configure your OAuth server to allow redirects** to your callback URL.
### Prerequisites
* An authentication system that can generate and sign JWTs.
* A backend service that can create redirect URLs.
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Full Authentication** or **Partial Authentication**.
3. Select **JWT**.
4. Enter the URL of your existing login flow and select **Save changes**.
5. Select **Generate new key**.
6. Store your key securely where it can be accessed by your backend.
Modify your existing login flow to include these steps after user authentication:
* Create a JWT containing the authenticated user's info in the `User` format. See [User data format](/authentication-personalization/personalization-setup#user-data-format) for more information.
* Sign the JWT with your secret key, using the EdDSA algorithm.
* Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash.
### Example
Your documentation is hosted at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don't have a dashboard).
Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication.
After verifying user credentials:
* Generate a JWT with user data in Mintlify's format.
* Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
```ts TypeScript
import * as jose from 'jose';
import { Request, Response } from 'express';
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,
lastName: res.locals.user.lastName,
},
};
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
.setExpirationTime('10 s') // 10 second JWT expiration
.sign(signingKey);
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
}
```
```python Python
import jwt # pyjwt
import os
from datetime import datetime, timedelta
from fastapi.responses import RedirectResponse
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
@router.get('/auth')
async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
'lastName': current_user.last_name,
},
},
key=private_key,
algorithm='EdDSA'
)
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
### Redirecting unauthenticated users
When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL:
1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`.
2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`.
3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. User lands in their original destination.
## Making pages public
When using partial authentication, all pages are protected by default. You can make specific pages viewable without authentication at the page or group level with the `public` property.
### Page level
To make a page public, add `public: true` to the page's frontmatter.
```mdx Public page example
---
title: "Public page"
public: true
---
```
### Group level
To make all pages in a group public, add `"public": true` beneath the group's name in the `navigation` object of your `docs.json`.
```json Public group example
{
"navigation": {
"groups": [
{
"group": "Public group",
"public": true,
"icon": "play",
"pages": [
"quickstart",
"installation",
"settings"
]
},
{
"group": "Private group",
"icon": "pause",
"pages": [
"private-information",
"secret-settings"
]
}
]
}
}
```
# Personalization setup
Source: https://mintlify.com/docs/authentication-personalization/personalization-setup
Let users log in for customized documentation experiences
Personalization customizes your documentation for each user when they are logged in. For example, you can prefill their API keys, show content specific to their plan or role, or hide sections they don't need access to.
## Personalization features
Customize content with these personalization capabilities.
### API key prefilling
Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work.
### Dynamic MDX content
Display dynamic content based on user information like name, plan, or organization using the `user` variable.
```jsx
Welcome back, {user.firstName}! Your {user.org?.plan} plan includes...
```
See the [User data format](#user-data-format) section below for detailed examples and implementation guidance.
### Page visibility
Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user.
Users will only see pages for `groups` that they are in.
```mdx
---
title: "Managing your users"
description: "Adding and removing users from your organization"
groups: ["admin"]
---
```
## User data format
When implementing personalization, your system returns user data in a specific format that enables content customization. This data can be sent as either a raw JSON object or within a signed JWT, depending on your handshake method. The shape of the data is the same for both.
```tsx
type User = {
expiresAt?: number;
groups?: string[];
content?: Record;
apiPlaygroundInputs?: {
header?: Record;
query?: Record;
cookie?: Record;
server?: Record;
};
};
```
Session expiration time in **seconds since epoch**. If the user loads a page after this time, their stored data is automatically deleted and they must reauthenticate.
For JWT handshakes: This differs from the JWT's `exp` claim, which determines when a JWT is considered invalid. Set the JWT `exp` claim to a short duration (10 seconds or less) for security. Use `expiresAt` for the actual session length (hours to weeks).
List of groups the user belongs to. Pages with matching `groups` in their frontmatter are visible to this user.
**Example**: User with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups.
Custom data accessible in your `MDX` content via the `user` variable. Use this for dynamic personalization throughout your documentation.
**Basic example**:
```json
{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
```
**Usage in `MDX`**:
```mdx
Welcome back, {user.firstName}! Your {user.plan} plan includes...
```
With the example `user` data, this would render as: Welcome back, Ronan! Your Enterprise plan includes...
**Advanced conditional rendering**:
```jsx
Authentication is an enterprise feature. {
user.org === undefined
? <>To access this feature, first create an account at the Mintlify dashboard.
: user.org.plan !== 'enterprise'
? <>You are currently on the ${user.org.plan ?? 'free'} plan. See our pricing page for information about upgrading.
: <>To request this feature for your enterprise org, contact your admin.
}
```
The information in `user` is only available for logged-in users. For logged-out users, the value of `user` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `user` fields. For example, `{user.org?.plan}`.
User-specific values that prefill API playground fields. Saves users time by auto-populating their data when testing APIs.
**Example**:
```json
{
"header": { "X-API-Key": "user_api_key_123" },
"server": { "subdomain": "foo" },
"query": { "org_id": "12345" }
}
```
If a user makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as an `apiPlaygroundInputs` field. This value will be prefilled on any API page with the `subdomain` value.
The `header`, `query`, and `cookie` fields will only prefill if they are part of your [OpenAPI security scheme](https://swagger.io/docs/specification/authentication/). If a field is in either the `Authorization` or `Server` sections, it will prefill. Creating a standard header parameter named `Authorization` will not enable this feature.
### Example user data
```json
{
"expiresAt": 1735689600,
"groups": ["admin", "beta-users"],
"content": {
"firstName": "Jane",
"lastName": "Smith",
"company": "TechCorp",
"plan": "Enterprise",
"region": "us-west"
},
"apiPlaygroundInputs": {
"header": {
"Authorization": "Bearer abc123",
"X-Org-ID": "techcorp"
},
"server": {
"environment": "production",
"region": "us-west"
}
}
}
```
## Configuring personalization
Select the handshake method that you want to configure.
### Prerequisites
* A login system that can generate and sign JWTs
* A backend service that can create redirect URLs
### Implementation
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Personalization**.
3. Select **JWT**.
4. Enter the URL of your existing login flow and select **Save changes**.
5. Select **Generate new key**.
6. Store your key securely where it can be accessed by your backend.
Modify your existing login flow to include these steps after user login:
* Create a JWT containing the logged-in user's info in the `User` format. See the [User data format](#user-data-format) section above for more information.
* Sign the JWT with the secret key, using the ES256 algorithm.
* Create a redirect URL back to your docs, including the JWT as the hash.
### Example
Your documentation is hosted at `docs.foo.com`. You want your docs to be separate from your dashboard (or you don't have a dashboard) and enable personalization.
Generate a JWT secret. Then create a login endpoint at `https://foo.com/docs-login` that initiates a login flow to your documentation.
After verifying user credentials:
* Generate a JWT with user data in Mintlify's format.
* Sign the JWT and redirect to `https://docs.foo.com#{SIGNED_JWT}`.
```ts
import * as jose from 'jose';
import { Request, Response } from 'express';
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256');
export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,
lastName: res.locals.user.lastName,
},
};
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'ES256' })
.setExpirationTime('10 s')
.sign(signingKey);
return res.redirect(`https://docs.foo.com#${jwt}`);
}
```
### Preserving page anchors
To redirect users to specific sections after login, use this URL format: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.
**Example**:
* Original URL: `https://docs.foo.com/quickstart#step-one`
* Redirect URL: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
### Prerequisites
* An OAuth server that supports the Auth Code with PKCE Flow
* Ability to create an API endpoint accessible by OAuth access tokens
### Implementation
Create an API endpoint that:
* Accepts OAuth access tokens for authentication.
* Returns user data in the `User` format. See the [User data format](#user-data-format) section above for more information.
* Defines the scopes for access.
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Personalization**.
3. Select **OAuth** and configure these fields:
* **Authorization URL**: Your OAuth authorization endpoint.
* **Client ID**: Your OAuth 2.0 client identifier.
* **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Must match the scopes of the endpoint that you configured in the first step.
* **Token URL**: Your OAuth token exchange endpoint.
* **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step.
4. Select **Save changes**
1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Add this URL as an authorized redirect URL in your OAuth server configuration.
### Example
Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.
**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope and responds with the user's custom data:
```json
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configure your OAuth server details** in your dashboard:
* **Authorization URL**: `https://auth.foo.com/authorization`
* **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
* **Scopes**: `['docs-user-info']`
* **Token URL**: `https://auth.foo.com/exchange`
* **Info API URL**: `https://api.foo.com/docs/user-info`
**Configure your OAuth server** to allow redirects to your callback URL.
### Prerequisites
* A dashboard or user portal with cookie-based session authentication.
* Ability to create an API endpoint at the same origin or subdomain as your dashboard.
* If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`.
* If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`.
* Your docs are hosted at the same domain or subdomain as your dashboard.
* If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`.
* If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`.
### Implementation
Create an API endpoint that:
* Uses your existing session authentication to identify users
* Returns user data in the `User` format (see the [User data format](#user-data-format) section above)
* If the API domain and the docs domain **do not exactly match**:
* Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`).
* Set your API's `Access-Control-Allow-Credentials` header to `true`.
Only enable CORS headers on this specific endpoint, not your entire dashboard API.
1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Select **Personalization**.
3. Select **Shared Session**.
4. Enter your **Info API URL**, which is the endpoint from the first step.
5. Enter your **Login URL**, where users log into your dashboard.
6. Select **Save changes**.
### Examples
#### Dashboard at subdomain, docs at subdomain
You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`.
**Setup process**:
1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
2. **Add CORS headers** for this route only:
* `Access-Control-Allow-Origin`: `https://docs.foo.com`
* `Access-Control-Allow-Credentials`: `true`
3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`.
#### Dashboard at subdomain, docs at root
You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`.
**Setup process**:
1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
2. **Add CORS headers** for this route only:
* `Access-Control-Allow-Origin`: `https://foo.com`
* `Access-Control-Allow-Credentials`: `true`
3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`.
#### Dashboard at root, docs at root
You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`.
**Setup process**:
1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data.
2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info`
No CORS configuration is needed since the dashboard and docs share the same domain.
# Code
Source: https://mintlify.com/docs/code
Display 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
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 lines icon="java"
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx
```java HelloWorld.java lines icon="java"
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
## Code block options
You can 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.
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
### Title
Add a title to label your code example. Use `title="Your title"` or a string on a single line.
```javascript Code Block Example
const hello = "world";
```
````mdx
```javascript Code Block 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="square-js"
const hello = "world";
```
````mdx
```javascript 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 highlight= {1-2,5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx
```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 Focus Example focus= {2,4-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx
```javascript Line Focus 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
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx
```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
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()
```
````mdx
```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
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
```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 icon="code" lines
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
````text
```js Diff Example icon="code" lines
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
console.log("Hello, World!"); // [!code --]
console.log(greeting); // [!code ++]
}
sayHello();
```
````
# Accordions
Source: https://mintlify.com/docs/components/accordions
Collapsible components 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
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````mdx Accordion example
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
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
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`.
# 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.
To add a banner, use the `banner` property in your `docs.json`:
```json Product announcements wrap
"banner": {
"content": "🚀 Version 2.0 is now live! See our [changelog](/changelog) for details.",
"dismissible": true
}
```
```json Maintenance notices wrap
"banner": {
"content": "⚠️ Scheduled maintenance: API will be unavailable December 15, 2-4 AM UTC",
"dismissible": false
}
```
```json Required actions wrap
"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 add eye-catching context to your 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
This adds a note in the content
```
This raises a warning to watch out for
```mdx
This raises a warning to watch out for
```
This draws attention to important information
```mdx
This draws attention to important information
```
This suggests a helpful tip
```mdx
This suggests a helpful tip
```
This brings us a checked status
```mdx
This brings us a checked status
```
This is a danger callout
```mdx
This is a danger callout
```
This is a custom callout
```mdx wrap
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
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
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
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
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
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 (e.g., `#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
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!");
}
}
```
## 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
```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
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!");
}
}
```
````mdx highlight=1
```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!");
}
}
```
````
# Columns
Source: https://mintlify.com/docs/components/columns
Show cards side by side in a grid format
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
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
curl --request POST \
--url https://dog-api.kinduff.com/api/facts
```
```json Response
{ "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
```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
```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
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
Set parameters for your API or SDK references
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
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
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
Wrap images or other components in a container
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
You can add additional context to an image using the optional `caption` prop.
## Properties
Optional caption text to show centered under your component.
```mdx Frame
```
```mdx Frame with a caption
```
# Icons
Source: https://mintlify.com/docs/components/icons
Use icons from popular icon libraries
Use icons from Font Awesome, Lucide, SVGs, external URLs, or files in your project to enhance your documentation.
```mdx Icon example
```
## Inline icons
Icons are placed inline when used within a paragraph.
The documentation you want, effortlessly.
```markdown Inline icon example
The documentation you want, effortlessly.
```
## 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.
# Mermaid
Source: https://mintlify.com/docs/components/mermaid-diagrams
Display diagrams using Mermaid
[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
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
```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
```mermaid
// Your mermaid diagram code here
```
````
# Panel
Source: https://mintlify.com/docs/components/panel
Specify the content of the right side panel
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
Pin info to the side panel. Or add any other component.
```
Pin info to the side panel. Or add any other component.
# Steps
Source: https://mintlify.com/docs/components/steps
Sequence content using the Steps component
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
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
Toggle content using the Tabs component
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
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
☝️ 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
Show a definition when you hover over text
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
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
Keep track of changes and updates
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
This is an update with a label, description, and tag.
```
Use multiple `Update` components to create [changelogs](/guides/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.
# Contact support
Source: https://mintlify.com/docs/contact-support
We're here to help you get the most out of Mintlify
## Ask our docs
Select Command + I to start a chat with our AI assistant trained on our documentation.
## Watch video tutorials
Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tutorials and guides on using Mintlify.
## Message support
Send us a message from your [dashboard](https://dashboard.mintlify.com/) by selecting **Support** in the sidebar.
We aim to respond to all requests within 24 hours, but delays may occur during busy times.
## Email support
If you can't access your dashboard, please email us at [support@mintlify.com](mailto:support@mintlify.com).
# Working with branches
Source: https://mintlify.com/docs/editor/branches
Use branches to make and review changes without affecting your live documentation
Branches are a feature of version control that point to specific commits in your repository. Your deployment branch, usually called `main`, represents the content that is used to build your live documentation. All other branches are independent of your live docs unless you choose to merge them into your deployment branch.
Branches let you create separate instances of your documentation to make changes, get reviews, and try new approaches before publishing. Your team can work on branches to update different parts of your documentation at the same time without affecting what users see on your live site until you publish any changes.
We recommend always working from branches when updating documentation to keep your live site stable and enable review workflows.
* Name branches clearly so teammates understand what you're working on.
* Delete branches after merging to keep your repository organized.
* Let your team know when you're working on major changes that might affect their work.
## Creating a branch
1. Select the branch name in the editor toolbar (usually `main` by default).
2. Select **New Branch**.
3. Enter a descriptive name for your branch like `update-getting-started` or `fix-api-examples`.
4. Select **Create Branch**.
## Saving changes on a branch
To save your changes on a branch, select the **Save Changes** button in the top-right corner of the editor. This creates a commit and pushes your work to your branch.
## Switching branches
1. Select the branch name in the editor toolbar.
2. Select the branch you want to switch to from the dropdown menu.
Unsaved changes are lost when switching branches. Make sure to save or publish your work before switching branches.
# Managing content
Source: https://mintlify.com/docs/editor/content-management
Create, edit, and organize your documentation pages
## Navigating your files
Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor.
Press Command + P (Ctrl + P on Windows) to search for files by name.
## Creating new pages
Select the **Create a new file** icon in the file explorer sidebar.
Filenames must end in `.mdx`. For example, `api-reference.mdx` or `getting-started.mdx`.
Press Enter to create the file. It will open automatically in the editor, ready for content to be added.
## Organizing your navigation
Add new pages to your site navigation by editing your `docs.json` file.
Find and open the `docs.json` file in your root directory using the file explorer.
Find the spot in the `docs.json` file where you want to add your new page.
Insert your page filename (without the `.mdx` extension) in the appropriate group's `pages` array.
### Example: Adding a themes page
```json title="Adding a themes page to the Profile group" highlight="18"
{
"navigation": {
"groups": [
{
"group": "Getting started",
"pages": [
"index",
"quickstart",
"installation"
]
},
{
"group": "Profile",
"pages": [
"settings",
"account-types",
"dashboard",
"themes"
]
}
]
}
}
```
## Editing content
Make changes to your pages using visual mode or Markdown mode in the editor.
In visual mode, press / to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation.
In Markdown mode, you can directly edit the `MDX` of your pages. This can be helpful when you need to:
* Set specific component properties
* Work with complex nested components
* Copy and paste `MDX` content from other sources
# Getting started with the web editor
Source: https://mintlify.com/docs/editor/getting-started
Learn how to create and edit documentation with the web editor
The web editor is a visual interface for creating, editing, and reviewing documentation directly in your browser.
* **Visual editing**: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published.
* **Git synchronization**: All changes automatically sync with your Git repository to maintain version control.
* **Team collaboration**: Multiple people can work on documentation simultaneously.
* **Component integration**: Add callouts, code blocks, and other components with slash commands.
* **No setup required**: Start writing immediately from your dashboard.
## Web editor workflow
Here is how you'll typically work in the web editor:
Create a branch or make changes directly to your deployment branch. We recommend creating a branch so that you can preview your changes before they go live.
Navigate to an existing file in the sidebar or create a new one using the file explorer.
Make changes in the web editor. Try switching between visual mode and Markdown mode using the toggle in the top-right corner to see which mode you prefer.
Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct.
If you're working on your deployment branch, publish your changes directly from the web editor. On other branches, you'll create a pull request for review before publishing.
## Editor modes
The web editor has two modes to accommodate different editing preferences and needs. Use the toggle in the top right corner of the editor toolbar to switch between editing modes.
### Visual mode
Visual mode provides a WYSIWYG experience where the changes that you make in the editor are the changes that will be published to your documentation site. This mode is ideal for when you want to see how your changes will look in real-time.
Press `/` to open the component menu and add styled content, callouts, code snippets, or other components.
### Markdown mode
Markdown mode provides direct access to the underlying `MDX` code of your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in Markdown syntax.
## Next steps
* Learn fundamental [Git concepts](/editor/git-concepts).
* Learn best practices for collaborating with [branches](/editor/branches).
* Explore [content management](/editor/content-management) with the web editor.
* Understand [publishing options](/editor/publishing) for different scenarios.
# Git concepts
Source: https://mintlify.com/docs/editor/git-concepts
Learn Git fundamentals for the docs-as-code workflow
Git is a version control system that allows you to track changes to your documentation and collaborate with team members. With Git, for every file in your project, you can see what changed, when, and why. Git also makes it easy to revert to previous versions of files if you ever need to.
The web editor performs some Git operations behind the scenes. Understanding these concepts will help you work more effectively with the web editor and collaborate with team members who are working in their local development environments.
## Core Git concepts
Your documentation's source where all files and their history are stored. The web editor connects to your repository to access and modify content.
A saved snapshot of your changes at a specific point in time. Each commit includes a message describing what changed and creates a permanent record in your project history.
A branch points to a specific commit in your repository. Your live documentation is built from a deployment branch. You can have any number of other branches with changes that are not yet published to your live documentation. If you want to incorporate the changes from a branch into your live documentation, you can merge the branch into your deployment branch through a pull request.
Use branches to work on changes without affecting your live documentation, safely experiment with new features, and get reviews before publishing.
The primary branch of your project that your live documentation content is built from. Changes to this branch are automatically published to your documentation site. Often called `main`, but you can set any branch as your deployment branch.
A way to propose merging your changes on a branch into your live documentation. Allows for review and discussion before changes go live. Commonly called a PR, and also called a merge request in GitLab.
A diff (or difference) shows the changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified, making it easy to identify what changed.
## How the web editor uses Git
The web editor connects to your Git repository through the [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab) and automates common Git operations.
When you:
* **Open a file**: The editor fetches the latest version from your repository, ensuring you're always working with up to date content.
* **Make changes**: The editor tracks your changes as a draft that can become a commit when you're ready to save your work.
* **Save changes**: The editor makes a commit with your changes, preserving your work in the project history.
* **Create a branch**: The editor creates a new branch in your repository that can be used by anyone with access to the repository so they can collaborate and review changes.
* **Publish on your deployment branch**: The editor commits and pushes directly to your deployment branch, which publishes your changes immediately.
* **Publish on other branches**: The editor creates a pull request, which allows you to get feedback from others before merging your changes into your deployment branch.
## Git best practices
Every team will develop their own workflows and preferences, but these are some general best practices to get you started.
* **Write descriptive commit messages**: Be specific about what changed using active language.
* **Use descriptive branch names**: Branch names should explain the work being done and be meaningful to someone who is looking at the branches in your repository.
* **Keep branches focused**: Keep the changes on a branch focused on a specific task or project.
* **Delete branches after merging**: Delete branches when you no longer need them to keep your repository tidy.
# Keyboard shortcuts
Source: https://mintlify.com/docs/editor/keyboard-shortcuts
Shortcuts for the web editor
The web editor supports all common keyboard shortcuts such as copy, paste, undo, and select all, and the following shortcuts:
| Command | macOS | Windows |
| :------------------------------- | :----------------------------------------------- | :--------------------------------------------------- |
| **Search files** | Cmd + P | Control + P |
| **Add link to highlighted text** | Cmd + K | Control + K |
| **Add line break** | Cmd + Enter | Control + Enter |
| **Bold** | Cmd + B | Control + B |
| **Italic** | Cmd + I | Control + I |
| **Underline** | Cmd + U | Control + U |
| **Strikethrough** | Cmd + Shift + S | Control + Shift + S |
| **Code** | Cmd + E | Control + E |
| **Normal text** | Cmd + Alt + 0 | Control + Alt + 0 |
| **Heading 1** | Cmd + Alt + 1 | Control + Alt + 1 |
| **Heading 2** | Cmd + Alt + 2 | Control + Alt + 2 |
| **Heading 3** | Cmd + Alt + 3 | Control + Alt + 3 |
| **Heading 4** | Cmd + Alt + 4 | Control + Alt + 4 |
| **Ordered list** | Cmd + Shift + 7 | Control + Shift + 7 |
| **Unordered list** | Cmd + Shift + 8 | Control + Shift + 8 |
| **Blockquote** | Cmd + Shift + B | Control + Shift + B |
| **Subscript** | Cmd + , | Control + , |
| **Superscript** | Cmd + . | Control + . |
# Publishing your changes
Source: https://mintlify.com/docs/editor/publishing
Deploy your documentation updates directly to production or through pull requests
How your changes are published depends on which branch you are working on:
* **Deployment branch**: Publishing updates your live site immediately.
* **Other branches**: Publishing creates a pull request so you can review changes before they are deployed to production.
## Pull requests and reviewing changes
Pull requests let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content.
Even if you're working solo, pull requests are valuable for previewing changes and maintaining a clear history of updates.
### Creating a pull request
Make sure all your changes are saved on your branch using **Save Changes**.
Select **Publish Pull Request** in the top-right corner of the editor.
Write a clear title and description explaining:
* What changes you made
* Why you made them
* Any specific areas that need review
Select **Publish Pull Request**. The editor will provide a link to view your pull request.
## Reviewing pull requests
Once your pull request is created:
1. **Review changes**: You and your team members can review your pull request in your Git provider like GitHub or GitLab.
2. **Leave feedback**: Add comments or request changes.
3. **Make additional changes**: Make additional changes in the web editor. When you save changes, the editor pushes them to your pull request.
4. **Approve**: Approve the pull request when you're satisfied with the changes.
5. **Merge**: Merge the pull request when you're ready to deploy your changes to production.
# Troubleshooting the web editor
Source: https://mintlify.com/docs/editor/troubleshooting
Solutions to common issues
Find solutions to common issues you might encounter while using the web editor.
**Possible causes:**
* Deployment is still in progress
* Browser caching issues
* Build or deployment errors
**Solutions:**
1. Check deployment status in your dashboard.
2. Hard refresh your browser (Ctrl + F5 or Cmd + Shift + R)
3. Clear your browser cache.
**Possible causes:**
* Insufficient permissions to the Git repository
* Authentication issues with your Git provider
**Solutions:**
1. Verify you have correct access to the repository.
2. Check if your Git integration is properly configured.
3. Review the [Editor Permissions](/advanced/dashboard/permissions) documentation.
**Possible causes:**
* Network connectivity problems
* Large documentation repositories
**Solutions:**
1. Check your internet connection.
2. Refresh the page.
3. Contact support if the issue persists.
**Possible causes:**
* Invalid MDX syntax in files
* Missing or corrupted files
* Large file sizes causing timeouts
**Solutions:**
1. Check the file syntax for MDX formatting errors
2. Verify the file exists in your repository.
# Assistant
Source: https://mintlify.com/docs/guides/assistant
Help users succeed with your product and find answers faster
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, providing users with immediate access to contextual help.
The assistant uses agentic RAG (retrieval-augmented generation) with tool calling powered by Claude Sonnet 4. 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.
## Configuring the assistant
The assistant is enabled by default for Pro and Custom plans. You can manage the assistant from your [dashboard](https://dashboard.mintlify.com/products/assistant/settings), including enabling or disabling it, configuring response handling, and setting a spend limit.
### Assistant status
Toggle the assistant status to enable or disable the assistant for your documentation site.
### Assistant deflection
Enable the assistant to redirect unanswered questions to your support team. Provide an email address that the assistant will provide 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).
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.
You can use the following filtering syntax when you configure external sites:
* **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
### Spend limit
Set a spend limit to control what happens if you reach your message allowance. By default, the assistant will continue to answer user questions after you reach your message allowance, which incurs overages.
In the **Billing** tab of the [Assistant Configurations](https://dashboard.mintlify.com/products/assistant/settings) page, you can set a spend limit for assistant messages beyond your allowance. When you reach your spend limit, the assistant is disabled until your message allowance resets.
You can also set usage alerts to receive an email when you reach a certain percentage of your spend limit.
## Using the assistant
Users can access the assistant in three ways:
* **Keyboard shortcuts**: ? or Command + I (Ctrl + I on Windows)
* **Assistant button** next to the search bar
* **URLs** with `?assistant=open` appended will open the assistant when the page loads. For example, [https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open).
Both methods open a chat panel on the right side of your docs. Users can ask any question and the assistant will search your documentation for an answer. If no relevant information is found, the assistant will respond that it cannot answer the question.
## 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](/guides/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.
# Changelogs
Source: https://mintlify.com/docs/guides/changelogs
Post product updates in your docs with a subscribable RSS feed
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
---
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
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](/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
<![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
---
rss: true
---
```
# Claude Code
Source: https://mintlify.com/docs/guides/claude-code
Configure Claude Code to help write, review, and update your docs
Claude Code is an agentic command line tool that can help you maintain your documentation. It can write new content, review existing pages, and keep docs up to date.
You can train Claude Code to understand your documentation standards and workflows by adding a `CLAUDE.md` file to your project and refining it over time.
## Getting started
**Prerequisites:**
* Active Claude subscription (Pro, Max, or API access)
**Setup:**
1. Install Claude Code:
```bash
npm install -g @anthropic-ai/claude-code
```
2. Navigate to your docs directory.
3. (Optional) Add the `CLAUDE.md` file below to your project.
4. Run `claude` to start.
## CLAUDE.md template
Save a `CLAUDE.md` file at the root of your docs directory to help Claude Code understand your project. This file trains Claude Code on your documentation standards, preferences, and workflows. See [Manage Claude's memory](https://docs.anthropic.com/en/docs/claude-code/memory) in the Anthropic docs for more information.
Copy this example template or make changes for your docs specifications:
```mdx
# Mintlify documentation
## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information
## Project context
- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components
## Content strategy
- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability of information
- Make content evergreen when possible
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes
## docs.json
- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
## Frontmatter requirements for pages
- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation
## Writing standards
- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links
## Git workflow
- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks
## Do not
- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification
```
## Sample prompts
Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs.
### Convert notes to polished docs
Turn rough drafts into proper Markdown pages with components and frontmatter.
**Example prompt:**
```text wrap
Convert this text into a properly formatted MDX page: [paste your text here]
```
### Review docs for consistency
Get suggestions to improve style, formatting, and component usage.
**Example prompt:**
```text wrap
Review the files in docs/ and suggest improvements for consistency and clarity
```
### Update docs when features change
Keep documentation current when your product evolves.
**Example prompt:**
```text wrap
Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples
```
### Generate comprehensive code examples
Create multi-language examples with error handling.
**Example prompt:**
```text wrap
Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling
```
## Extending Claude Code
Beyond manually prompting Claude Code, you can integrate it with your existing workflows.
### Automation with GitHub Actions
Run Claude Code automatically when code changes to keep docs up to date. You can trigger documentation reviews on pull requests or update examples when API changes are detected.
### Multi-instance workflows
Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss.
### Team collaboration
Share your refined `CLAUDE.md` file with your team to ensure consistent documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process.
### Custom commands
Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team.
# Content Security Policy (CSP) configuration
Source: https://mintlify.com/docs/guides/csp-configuration
Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies
Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. Mintlify serves a default CSP that protects most sites. If you host your documentation behind a reverse proxy or firewall, that overwrites the default CSP, you may need to configure CSP headers for features to function properly.
## CSP directives
The following CSP directives are used to control which resources can be loaded:
* `script-src`: Controls which scripts can be executed
* `style-src`: Controls which stylesheets can be loaded
* `font-src`: Controls which fonts can be loaded
* `img-src`: Controls which images, icons, and logos can be loaded
* `connect-src`: Controls which URLs can be connected to for API calls and WebSocket connections
* `frame-src`: Controls which URLs can be embedded in frames or iframes
* `default-src`: Fallback for other directives when not explicitly set
## Domain whitelist
| Domain | Purpose | CSP directive | Required |
| :------------------------------ | :-------------------- | :-------------------------- | :------- |
| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | `style-src`, `font-src` | Required |
| `*.mintlify.dev` | Documentation content | `connect-src` | Required |
| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | `img-src` | Required |
| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | Optional |
| `cdn.segment.com` | Segment analytics | `script-src`, `connect-src` | Optional |
| `plausible.io` | Plausible analytics | `script-src`, `connect-src` | Optional |
| `tag.clearbitscripts.com` | Clearbit tracking | `script-src` | Optional |
| `cdn.heapanalytics.com` | Heap analytics | `script-src` | Optional |
| `chat.cdn-plain.com` | Plain chat widget | `script-src` | Optional |
| `chat-assets.frontapp.com` | Front chat widget | `script-src` | Optional |
## Example CSP configuration
Only include domains for services that you use. Remove any analytics domains that you have not configured for your documentation.
```text wrap
Content-Security-Policy:
default-src 'self';
script-src 'self' 'unsafe-inline' 'unsafe-eval' www.googletagmanager.com cdn.segment.com plausible.io tag.clearbitscripts.com cdn.heapanalytics.com
chat.cdn-plain.com chat-assets.frontapp.com;
style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net;
font-src 'self' d4tuoctqmanu0.cloudfront.net;
img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net;
connect-src 'self' *.mintlify.dev www.googletagmanager.com cdn.segment.com plausible.io;
frame-src 'self' *.mintlify.dev;
```
## Common configurations by proxy type
Most reverse proxies support adding custom headers.
### Cloudflare configuration
Create a Response Header Transform Rule:
1. In your Cloudflare dashboard, go to **Rules > Overview**.
2. Select **Create rule > Response Header Transform Rule**.
3. Configure the rule:
* **Modify response header**: Set static
* **Header name**: `Content-Security-Policy`
* **Header value**:
```text wrap
default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;
```
4. Deploy your rule.
### AWS CloudFront configuration
Add a response headers policy in CloudFront:
```json
{
"ResponseHeadersPolicy": {
"Name": "MintlifyCSP",
"Config": {
"SecurityHeadersConfig": {
"ContentSecurityPolicy": {
"ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;",
"Override": true
}
}
}
}
}
```
### Vercel configuration
Add to your `vercel.json`:
```json
{
"headers": [
{
"source": "/(.*)",
"headers": [
{
"key": "Content-Security-Policy",
"value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net; font-src 'self' d4tuoctqmanu0.cloudfront.net; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net; connect-src 'self' *.mintlify.dev; frame-src 'self' *.mintlify.dev;"
}
]
}
]
}
```
## Troubleshooting
Identify CSP violations in your browser console:
1. Open your browser's Developer Tools.
2. Go to the **Console** tab.
3. Look for errors starting with:
* `Content Security Policy: The page's settings blocked the loading of a resource`
* `Refused to load the script/stylesheet because it violates the following Content Security Policy directive`
* `Refused to connect to because it violates the following Content Security Policy directive`
# Cursor
Source: https://mintlify.com/docs/guides/cursor
Configure Cursor to be your writing assistant
Transform Cursor into a documentation expert that knows your components, style guide, and best practices.
## Using Cursor with Mintlify
Cursor rules provide persistent context about your documentation, ensuring more consistent suggestions that fit your standards and style.
* **Project rules** are stored in your documentation repository and shared with your team.
* **User rules** apply to your personal Cursor environment.
We recommend creating project rules for your docs so that all contributors have access to the same rules.
Create rules files in the `.cursor/rules` directory of your docs repo. See the [Cursor Rules documentation](https://docs.cursor.com/context/rules) for complete setup instructions.
## Example project rule
This rule provides Cursor with context to properly format Mintlify components and follow technical writing best practices.
You can use this example as-is or customize it for your documentation:
* **Writing standards**: Update language guidelines to match your style guide.
* **Component patterns**: Add project-specific components or modify existing examples.
* **Code examples**: Replace generic examples with real API calls and responses for your product.
* **Style and tone preferences**: Adjust terminology, formatting, and other rules.
Add this rule with any modifications as an `.mdc` file in the `.cursor/rules` directory of your docs repo.
````mdx wrap
# Mintlify technical writing rule
You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
## Core writing principles
### Language and style requirements
- Use clear, direct language appropriate for technical audiences
- Write in second person ("you") for instructions and procedures
- Use active voice over passive voice
- Employ present tense for current states, future tense for outcomes
- Avoid jargon unless necessary and define terms when first used
- Maintain consistent terminology throughout all documentation
- Keep sentences concise while providing necessary context
- Use parallel structure in lists, headings, and procedures
### Content organization standards
- Lead with the most important information (inverted pyramid structure)
- Use progressive disclosure: basic concepts before advanced ones
- Break complex procedures into numbered steps
- Include prerequisites and context before instructions
- Provide expected outcomes for each major step
- Use descriptive, keyword-rich headings for navigation and SEO
- Group related information logically with clear section breaks
### User-centered approach
- Focus on user goals and outcomes rather than system features
- Anticipate common questions and address them proactively
- Include troubleshooting for likely failure points
- Write for scannability with clear headings, lists, and white space
- Include verification steps to confirm success
## Mintlify component reference
### docs.json
- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
### Callout components
#### Note - Additional helpful information
Supplementary information that supports the main content without interrupting flow
#### Tip - Best practices and pro tips
Expert advice, shortcuts, or best practices that enhance user success
#### Warning - Important cautions
Critical information about potential issues, breaking changes, or destructive actions
#### Info - Neutral contextual information
Background information, context, or neutral announcements
#### Check - Success confirmations
Positive confirmations, successful completions, or achievement indicators
### Code components
#### Single code block
Example of a single code block:
```javascript config.js
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
#### Code group with multiple languages
Example of a code group:
```javascript Node.js
const response = await fetch('/api/endpoint', {
headers: { Authorization: `Bearer ${apiKey}` }
});
```
```python Python
import requests
response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
```curl cURL
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
#### Request/response examples
Example of request/response documentation:
```bash cURL
curl -X POST 'https://api.example.com/users' \
-H 'Content-Type: application/json' \
-d '{"name": "John Doe", "email": "john@example.com"}'
```
```json Success
{
"id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
```
### Structural components
#### Steps for procedures
Example of step-by-step instructions:
Run `npm install` to install required packages.
Verify installation by running `npm list`.
Create a `.env` file with your API credentials.
```bash
API_KEY=your_api_key_here
```
Never commit API keys to version control.
#### Tabs for alternative content
Example of tabbed content:
```bash
brew install node
npm install -g package-name
```
```powershell
choco install nodejs
npm install -g package-name
```
```bash
sudo apt install nodejs npm
npm install -g package-name
```
#### Accordions for collapsible content
Example of accordion groups:
- **Firewall blocking**: Ensure ports 80 and 443 are open
- **Proxy configuration**: Set HTTP_PROXY environment variable
- **DNS resolution**: Try using 8.8.8.8 as DNS server
```javascript
const config = {
performance: { cache: true, timeout: 30000 },
security: { encryption: 'AES-256' }
};
```
### Cards and columns for emphasizing information
Example of cards and card groups:
Complete walkthrough from installation to your first API call in under 10 minutes.
Learn how to authenticate requests using API keys or JWT tokens.
Understand rate limits and best practices for high-volume usage.
### API documentation components
#### Parameter fields
Example of parameter documentation:
Unique identifier for the user. Must be a valid UUID v4 format.
User's email address. Must be valid and unique within the system.
Maximum number of results to return. Range: 1-100.
Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
#### Response fields
Example of response field documentation:
Unique identifier assigned to the newly created user.
ISO 8601 formatted timestamp of when the user was created.
List of permission strings assigned to this user.
#### Expandable nested fields
Example of nested field documentation:
Complete user object with all associated data.
User profile information including personal details.
User's first name as entered during registration.
URL to user's profile picture. Returns null if no avatar is set.
### Media and advanced components
#### Frames for images
Wrap all images in frames:
#### Videos
Use the HTML video element for self-hosted video content:
Embed YouTube videos using iframe elements:
#### Tooltips
Example of tooltip usage:
API
#### Updates
Use updates for changelogs:
## New features
- Added bulk user import functionality
- Improved error messages with actionable suggestions
## Bug fixes
- Fixed pagination issue with large datasets
- Resolved authentication timeout problems
## Required page structure
Every documentation page must begin with YAML frontmatter:
```yaml
---
title: "Clear, specific, keyword-rich title"
description: "Concise description explaining page purpose and value"
---
```
## Content quality standards
### Code examples requirements
- Always include complete, runnable examples that users can copy and execute
- Show proper error handling and edge case management
- Use realistic data instead of placeholder values
- Include expected outputs and results for verification
- Test all code examples thoroughly before publishing
- Specify language and include filename when relevant
- Add explanatory comments for complex logic
- Never include real API keys or secrets in code examples
### API documentation requirements
- Document all parameters including optional ones with clear descriptions
- Show both success and error response examples with realistic data
- Include rate limiting information with specific limits
- Provide authentication examples showing proper format
- Explain all HTTP status codes and error handling
- Cover complete request/response cycles
### Accessibility requirements
- Include descriptive alt text for all images and diagrams
- Use specific, actionable link text instead of "click here"
- Ensure proper heading hierarchy starting with H2
- Provide keyboard navigation considerations
- Use sufficient color contrast in examples and visuals
- Structure content for easy scanning with headers and lists
## Component selection logic
- Use **Steps** for procedures and sequential instructions
- Use **Tabs** for platform-specific content or alternative approaches
- Use **CodeGroup** when showing the same concept in multiple programming languages
- Use **Accordions** for progressive disclosure of information
- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
- Use **ParamField** for API parameters, **ResponseField** for API responses
- Use **Expandable** for nested object properties or hierarchical information
````
# Deployments
Source: https://mintlify.com/docs/guides/deployments
Troubleshoot your deployments
Your documentation site automatically deploys when you push changes to your connected repository. This requires the Mintlify GitHub app to be properly installed and connected.
If your latest changes are not appearing on your live site, first check that the GitHub app is installed on the account or organization that owns your docs repository. See [GitHub troubleshooting](/settings/github#troubleshooting) for more information.
If the GitHub app is connected, but changes are still not deploying, you can manually trigger a rebuild from your dashboard.
## Manually triggering a deployment
Check that your latest commit appears in your docs repository and did not encounter any errors.
Go to your [dashboard](https://dashboard.mintlify.com) and select the deploy button.
# GEO guide: Optimize docs for AI search and answer engines
Source: https://mintlify.com/docs/guides/geo
Make your documentation more discoverable and cited more frequently by AI tools
Optimize your documentation for both traditional search engines and AI-powered answer engines like ChatGPT, Perplexity, and Google AI Overviews.
Generative Engine Optimization (GEO) focuses on being cited by AI systems through comprehensive content and structured information, while traditional SEO targets search result rankings.
## GEO quickstart
### Initial setup
1. **Make sure your docs are being indexed** in your `docs.json` settings
2. **Audit current pages** for missing descriptions and titles
### Content improvements
1. **Add comparison tables** to appropriate pages
2. **Audit headings** to ensure they answer common questions
3. **Improve internal linking** between related topics
4. **Test with AI tools** to verify accuracy
## GEO best practices
In general, well written and well structured documentation will have strong GEO. You should still prioritize writing for your users, and if your content is meeting their needs, you will be well on your way to optimizing for AI tools. Creating genuinely helpful content rather than optimizing for optimization's sake is rewarded by both traditional and AI search engines.
Focus on:
* Content aligned to user needs rather than keyword matching
* Structured, scannable information
* Direct answers to questions
### Format for clarity
These formatting practices help AI tools parse and understand your content:
* Don't skip heading levels (H1 → H2 → H3)
* Use specific object names instead of "it" or "this"
* Label code blocks with their programming language
* Give images descriptive alt text
* Link to related concepts to help AI understand relationships
### Answer questions directly
Write content that addresses specific user questions:
* Begin sections with the main takeaway
* Use descriptive headings that match common queries
* Break complex topics into numbered steps
## Mintlify configuration
Use these features to improve GEO.
### Add descriptive page metadata
Include clear titles and descriptions in your frontmatter:
```mdx
---
title: "API authentication guide"
description: "Complete guide to implementing API authentication with code examples"
---
```
### Configure global indexing settings
Add to your `docs.json`:
```json
{
"seo": {
"indexing": "all",
"metatags": {
"og:type": "website",
"og:site_name": "Your docs"
}
}
}
```
### LLMs.txt
LLMs.txt files help AI systems understand your documentation structure, similar to how sitemaps help search engines. Mintlify automatically generates LLMs.txt files for your docs. No configuration is required.
## Testing your documentation
Test various AI tools with questions about your product and documentation to see how well your docs are being cited.
**Ask AI assistants specific questions about your docs:**
* "How do I set up authentication using this API?"
* "Walk me through the installation process step by step"
**Check that tools provide:**
* Correct code samples
* Accurate step-by-step instructions
# Hidden pages
Source: https://mintlify.com/docs/guides/hidden-pages
Exclude pages from your navigation
Hidden pages are removed from your site's navigation but remain publicly accessible to anyone who knows their URL.
Use hidden pages for content that you want to be accessible on your site or referenced as context for AI tools, but not discoverable through the navigation.
For content requiring strict access control, you must configure [authentication](/authentication-personalization/authentication-setup).
If you want to hide pages for specific groups of users, use personalization to control [page visibility](/authentication-personalization/overview#page-visibility).
## Hiding a page
A page is hidden if it is not included in your `docs.json` navigation. To hide a page, remove it from your navigation structure.
Hidden pages use the same URL structure as regular pages based on their file path. For example, `guides/hidden-page.mdx` would be accessible at `docs.yoursite.com/guides/hidden-page`.
See an [example of a hidden page](/guides/hidden-page-example).
Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
## Hiding a group of pages
A group of pages is hidden if the `hidden` property is set to `true` in your `docs.json` file:
```json highlight={4}
"groups": [
{
"group": "Getting started",
"hidden": true,
"pages": [
"index",
"quickstart"
]
},
{
"group": "Guides",
"pages": [
"guides/hidden-page.mdx",
"guides/hidden-groups.mdx"
]
}
]
```
In this example, the `Getting started` group is hidden, but the `Guides` group is visible.
### Hiding a tab
You can also hide a tab by adding the `hidden` property to your `docs.json` file:
```json highlight={4}
"tabs": [
{
"tab": "Home",
"hidden": true,
"pages": [
"index",
"quickstart"
]
}
]
```
## Search, SEO, and AI indexing
By default, hidden pages are excluded from indexing for search engines, internal search within your docs, and as context for the AI assistant. To include hidden pages in search results and as context for the assistant, add the `seo` property to your `docs.json`:
```json
"seo": {
"indexing": "all"
}
```
To exclude a specific page, add `noindex: "true"` to its frontmatter.
# Migrations
Source: https://mintlify.com/docs/guides/migration
How to migrate documentation from your current platform
This guide helps you move your existing documentation to Mintlify. Choose automated migration for supported platforms or manual migration for complete control over the process.
## Choose your migration path
If you are migrating from Docusaurus, ReadMe, or GitBook, use our tools to automate your migration.
If you are migrating from any other platform, follow our guide to migrate your content.
Migrate your documentation using the [@mintlify/scraping package](https://www.npmjs.com/package/@mintlify/scraping). The package scrapes your content and converts it to use Mintlify components.
### Supported Platforms
}
horizontal
/>
}
horizontal
/>
}
horizontal
/>
If your documentation is hosted on another platform, see the manual migration steps.
### Installing the scraper
Install the `@mintlify/scraping` package to get started.
```bash
npm install @mintlify/scraping@latest -g
```
### Scraping pages and sections
The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default.
For large documentation sites, migrate smaller sections at a time rather than the entire site at once.
**Migrate entire sections:**
```bash
mintlify-scrape section https://your-docs-site.com/docs
```
**Migrate single pages:**
```bash
mintlify-scrape page https://your-docs-site.com/docs/getting-started
```
**Migrate OpenAPI specifications:**
```bash
mintlify-scrape openapi-file [openApiFilename]
```
### Add prepared content to your Mintlify project
After scraping your existing documentation platform, you are ready to build your docs on Mintlify.
Confirm that all of your pages have been migrated then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.
Migrate your documentation from any platform with full control over the process.
### Content migration
To migrate your content to Mintlify, you will need:
* A valid `docs.json` for your site settings and navigation. See [Global settings](/settings) and [Navigation](/navigation) for more information.
* An `MDX` file for each page of your documentation. See [Pages](/pages) for more information.
* (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information.
1. If your content is already in `MDX` format, copy the pages to your Mintlify project. Otherwise, convert your content to `MDX` format.
2. Create your `docs.json` referencing the paths to your `MDX` pages.
3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground.
### Asset migration
1. Copy assets to your repository's `images/` directory.
2. Update references in your `MDX` files:
```mdx
```
## Post-migration checklist
After completing your migration (automated or manual), we recommend checking:
* All pages render
* Navigation works as intended
* Internal links resolve properly
* Images and assets load correctly
* Code blocks display with proper syntax highlighting
* Search functionality works
* Deployment is configured
* Custom domain is set up
# Monorepo setup
Source: https://mintlify.com/docs/guides/monorepo
Deploy your docs from a repo that contains multiple projects
Configure Mintlify to deploy documentation from a specific directory within a monorepo. This setup allows you to maintain documentation alongside your code in repositories that contain multiple projects or services.
## Prerequisites
* Admin access to your Mintlify project.
* Documentation files organized in a dedicated directory within your monorepo.
* A valid `docs.json` in your documentation directory.
## Configure monorepo deployment
Navigate to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard.
1. Select the **Set up as monorepo** toggle button.
2. Enter the relative path to your docs directory. For example, if your docs are in the `docs` directory, enter `/docs`.
Do not include a trailing slash in the path.
3. Select **Save changes**.
# Windsurf
Source: https://mintlify.com/docs/guides/windsurf
Configure Windsurf to be your writing assistant
Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories.
## Using Windsurf with Mintlify
Windsurf's Cascade AI assistant can be tuned to write documentation according to your standards using Mintlify components. Workspace rules and memories provide persistent context about your project, ensuring more consistent suggestions from Cascade.
* **Workspace rules** are stored in your documentation repository and shared with your team.
* **Memories** provide individual context that builds up over time.
We recommend setting up workspace rules for shared documentation standards. You can develop memories as you work, but since they are not shared, they will not be consistent across team members.
Create workspace rules in the `.windsurf/rules` directory of your docs repo. See [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) in the Windsurf documentation for more information.
## Example workspace rule
This rule provides Cascade with context about Mintlify components and general technical writing best practices.
You can use this example rule as-is or customize it for your documentation:
* **Writing standards**: Update language guidelines to match your style guide.
* **Component patterns**: Add project-specific components or modify existing examples.
* **Code examples**: Replace generic examples with real API calls and responses for your product.
* **Style and tone preferences**: Adjust terminology, formatting, and other rules.
Save your rule as a `.md` file in the `.windsurf/rules` directory of your docs repo.
````mdx
# Mintlify technical writing rule
## Project context
- This is a documentation project on the Mintlify platform
- We use MDX files with YAML frontmatter
- Navigation is configured in `docs.json`
- We follow technical writing best practices
## Writing standards
- Use second person ("you") for instructions
- Write in active voice and present tense
- Start procedures with prerequisites
- Include expected outcomes for major steps
- Use descriptive, keyword-rich headings
- Keep sentences concise but informative
## Required page structure
Every page must start with frontmatter:
```yaml
---
title: "Clear, specific title"
description: "Concise description for SEO and navigation"
---
```
## Mintlify components
### docs.json
- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
### Callouts
- `` for helpful supplementary information
- `` for important cautions and breaking changes
- `` for best practices and expert advice
- `` for neutral contextual information
- `` for success confirmations
### Code examples
- When appropriate, include complete, runnable examples
- Use `` for multiple language examples
- Specify language tags on all code blocks
- Include realistic data, not placeholders
- Use `` and `` for API docs
### Procedures
- Use `` component for sequential instructions
- Include verification steps with `` components when relevant
- Break complex procedures into smaller steps
### Content organization
- Use `` for platform-specific content
- Use `` for progressive disclosure
- Use `` and `` for highlighting content
- Wrap images in `` components with descriptive alt text
## API documentation requirements
- Document all parameters with ``
- Show response structure with ``
- Include both success and error examples
- Use `` for nested object properties
- Always include authentication examples
## Quality standards
- Test all code examples before publishing
- Use relative paths for internal links
- Include alt text for all images
- Ensure proper heading hierarchy (start with h2)
- Check existing patterns for consistency
````
## Working with Cascade
Once your rules are set up, you can use Cascade to assist with various documentation tasks. See [Cascade](https://docs.windsurf.com/windsurf/cascade) in the Windsurf documentation for more information.
### Example prompts
**Writing new content**:
```text wrap
Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL.
```
**Improving existing content**:
```text wrap
Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow.
```
**Creating code examples**:
```text wrap
Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses.
```
**Maintaining consistency**:
```text wrap
Check if this new page follows our documentation standards and suggest any needed changes.
```
# Images and embeds
Source: https://mintlify.com/docs/image-embeds
Add images, videos, and iframes
Add images, embed videos, and include interactive content with iframes to your documentation.
All static assets in your docs repository are automatically served at the appropriate path on your domain. For example, if you have `/images/my-logo.png` in your repo, the image will be available at `https://docs.yoursite.com/images/my-logo.png`.
## 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
```
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 20MB. 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:
```html
```
#### Disable zoom functionality
To disable the default zoom on click for images, add the `noZoom` property:
```html highlight="4"
```
#### Link images
To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
```html
```
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
```
## 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
```
### Self-hosted videos
Use the HTML `
On the next page, enter the following attribute statements:
| Google Directory Attribute | App Attribute |
| -------------------------- | ------------- |
| `First name` | `firstName` |
| `Last name` | `lastName` |
Once this step is complete and users are assigned to the application, let our team know and we'll enable SSO for your account!
## Create CloudFront distribution
1. Navigate to [CloudFront](https://aws.amazon.com/cloudfront) inside the AWS console.
2. Select **Create distribution**.
3. For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is your project's unique subdomain.
4. For "Web Application Firewall (WAF)," enable security protections.
5. The remaining settings should be default.
6. Select **Create distribution**.
## Add default origin
1. After creating the distribution, navigate to the "Origins" tab.
2. Find your staging URL that mirrors the main domain. This is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app).
By this point, you should have two Origins: one with `[SUBDOMAIN].mintlify.app` and another with your staging URL.
## Set behaviors
Behaviors in CloudFront enable control over the subpath logic. At a high level, we're looking to create the following logic:
* **If a user lands on your custom subpath**, go to `[SUBDOMAIN].mintlify.dev`.
* **If a user lands on any other page**, go the current landing page.
1. Navigate to the "Behaviors" tab of your CloudFront distribution.
2. Select the **Create behavior** button and create the following behaviors.
### `/.well-known/*`
Create behaviors for Vercel domain verification paths with a **Path pattern** of `/.well-known/*` and set **Origin and origin groups** to your docs URL.
For "Cache policy", select **CachingDisabled** to ensure these verification requests pass through without caching.
### Your custom subpath with wildcard
Create a behavior with a **Path pattern** of your chosen subpath followed by `/*`, for example `/docs/*`, and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
These settings should exactly match your base subpath behavior. With the exception of the **Path pattern**.
* Set "Cache policy" to **CachingOptimized**.
* Set "Origin request policy" to **AllViewerExceptHostHeader**.
* Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**
### `/mintlify-assets/_next/static/*`
* Set "Cache policy" to **CachingOptimized**
* Set "Origin request policy" to **AllViewerExceptHostHeader**
* Set "Viewer protocol policy" to **Redirect HTTP to HTTPS**
### `Default (*)`
Lastly, we're going to edit the `Default (*)` behavior.
1. Change the default behavior's **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`).
2. Select **Save changes**.
### Check behaviors are set up correctly
If you follow the above steps, your behaviors should look like this:
All pages should be directing to your main landing page, but if you append your chosen subpath, for example `/docs`, to the URL, you should see it going to your Mintlify documentation instance.
## Connect with Route53
Now, we're going to bring the functionality of the CloudFront distribution into your primary domain.
4. Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option.
5. Select **Create records**.
## Enabling the contextual menu
Add the `contextual` field to your `docs.json` file and specify which options you want to include.
```json
{
"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
* **Thumbs rating only**: Simple thumbs up/down voting to gauge overall satisfaction with pages.
* **Code snippet feedback only**: Feedback specifically on code snippets.
* **Thumbs rating and contextual feedback**: Page voting plus detailed comments and reasons for ratings.
* **Thumbs rating and code snippet feedback**: Page voting plus feedback on code examples.
* **Thumbs rating, contextual, and code snippet feedback**: Complete feedback system with page voting, detailed comments, and code snippet feedback.
## Managing feedback
For contextual and code snippet feedback, you can set the status of a piece of feedback and add internal notes to track your work resolving user feedback.
### Changing feedback status
Select the status beside a piece of feedback to mark it as **Pending**, **In Progress**, **Resolved**, or **Dismissed**.
Best practices for setting feedback statuses:
* **Pending**: Feedback is awaiting review.
* **In Progress**: Feedback has been validated and is being worked on.
* **Resolved**: Feedback has been resolved.
* **Dismissed**: Feedback has been dismissed as not actionable, irrelevant, or inaccurate.
### Filtering by status
Use the status filter to control which feedback is displayed. Uncheck a status to hide all feedback with that status. By default, all feedback is displayed.
### Adding internal notes
Click on a piece of feedback to add an internal note. These notes are only visible to people with access to your dashboard.
Use notes to add information for collaboration, link relevant support or engineering tickets, or remember any other useful information.
## Using feedback data
Review your feedback data to:
* **Identify successful content**: Pages with the most positive feedback show what works well in your documentation.
* **Prioritize improvements**: Pages with the most negative feedback indicate what content might need attention.
* **Take action**: Make documentation updates based on direct user feedback.
# Improving your docs
Source: https://mintlify.com/docs/analytics/improving-docs
Use analytics data to make your documentation better
Improve your docs based on quantitative and qualitative data from your analytics dashboard.
## Cross-analytics insights
Combine information from multiple analytics sources to get a holistic view of your documentation.
### Correlate traffic and satisfaction
* **High traffic and low feedback scores**: Popular pages with a poor user experience. Prioritize improving these pages.
* **Low traffic and high feedback scores**: Documentation that is working well, but might not be discoverable. Consider promoting these pages.
* **High traffic and high feedback scores**: Your documentation's greatest hits. Review these pages for ideas to improve the rest of your content.
### Match search intent with content performance
* **High search volume and low page views**: Discoverability problems. Consider moving these pages or reviewing their frontmatter.
* **Popular search terms and low-confidence results**: Content gap opportunity. Consider adding more content or new content on these topics.
* **Top searches and negative feedback on matching pages**: User experience issues. Review the pages to see if they solve the user need that is being searched for.
## Put insights into action
Use these cross-analytics patterns to prioritize your documentation improvements:
* **Fix high-impact problems first**: Popular pages with poor feedback scores affect the most users.
* **Fill verified content gaps**: Low-confidence searches with high volume indicate unmet user needs.
* **Respond to user feedback**: Contextual and code snippet feedback can identify specific areas for improvement.
* **Align search and content**: Ensure your most-searched topics have comprehensive, well-organized pages.
* **Monitor rising search trends with no existing popular pages**: New content opportunities.
# Overview
Source: https://mintlify.com/docs/analytics/overview
View traffic and high-level insights about your documentation
The overview tab shows how many people have visited your docs, what pages are most popular, and where users are coming from. Use this information to identify which pages are most valuable to your users and track trends over time.
Access the overview metrics by navigating to the **Analytics** page in your [dashboard](https://dashboard.mintlify.com/products/analytics).
## Metrics
Use the range selector to adjust the time period for displayed data. Select visitors, views, or actions to display a line graph showing trends over the selected time period.
* **Visitors**: Unique visitors
* **Views**: Total page views
* **Actions**: Combined count of API calls, navbar link clicks, and CTA button clicks
* **Popular Pages**: Paths to the most-visited pages and their view counts
* **Referrers**: Top traffic sources directing users to your docs
## Using overview data
Review your overview analytics to:
* **Identify popular pages**: Use popular pages to understand what content is most important to your users so that you can make sure it is up to date and comprehensive.
* **Track traffic trends**: Monitor changes in traffic to understand the impact of updates or new content.
# Search
Source: https://mintlify.com/docs/analytics/search
Understand how users search within your documentation
Use the data on the search tab to understand what users are searching for and identify topics that need to be updated or expanded.
Access your search metrics by navigating to the **Analytics** page in your [dashboard](https://dashboard.mintlify.com/products/analytics).
## Search metrics
Use the range selector to adjust the time period for displayed data.
* **Total queries**: Search volume
* **Top searches**: Most-searched terms
* **Low-confidence searches**: Queries that may not have returned relevant results
## Using search data
Review your search analytics to:
* **Identify popular topics**: Use top searches to understand what content people want to find.
* **Find content gaps**: Low-confidence searches may indicate missing documentation or topics that need better coverage.
* **Improve discoverability**: Ensure that pages matching popular search terms are easy to find and well-organized.
# Playground
Source: https://mintlify.com/docs/api-playground/asyncapi/playground
Enable users to interact with your websockets
# AsyncAPI setup
Source: https://mintlify.com/docs/api-playground/asyncapi/setup
Create websocket reference pages with AsyncAPI
## Add an AsyncAPI specification file
To begin to create pages for your websockets, make sure you have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0). Your schema must follow the AsyncAPI specification 3.0+.
The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.
## Getting started
## Captions
You can add additional context to an image using the optional `caption` prop.
## Properties
```
```mdx Frame with a caption
### Features
* Responsive design
* Anchor for each update
* Generated RSS feed entry for each update
In Markdown mode, you can directly edit the `MDX` of your pages. This can be helpful when you need to:
* Set specific component properties
* Work with complex nested components
* Copy and paste `MDX` content from other sources
# Getting started with the web editor
Source: https://mintlify.com/docs/editor/getting-started
Learn how to create and edit documentation with the web editor
The web editor is a visual interface for creating, editing, and reviewing documentation directly in your browser.
* **Visual editing**: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published.
* **Git synchronization**: All changes automatically sync with your Git repository to maintain version control.
* **Team collaboration**: Multiple people can work on documentation simultaneously.
* **Component integration**: Add callouts, code blocks, and other components with slash commands.
* **No setup required**: Start writing immediately from your dashboard.
## Web editor workflow
Here is how you'll typically work in the web editor:
### Visual mode
Visual mode provides a WYSIWYG experience where the changes that you make in the editor are the changes that will be published to your documentation site. This mode is ideal for when you want to see how your changes will look in real-time.
Press `/` to open the component menu and add styled content, callouts, code snippets, or other components.
### Markdown mode
Markdown mode provides direct access to the underlying `MDX` code of your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in Markdown syntax.
## Next steps
* Learn fundamental [Git concepts](/editor/git-concepts).
* Learn best practices for collaborating with [branches](/editor/branches).
* Explore [content management](/editor/content-management) with the web editor.
* Understand [publishing options](/editor/publishing) for different scenarios.
# Git concepts
Source: https://mintlify.com/docs/editor/git-concepts
Learn Git fundamentals for the docs-as-code workflow
Git is a version control system that allows you to track changes to your documentation and collaborate with team members. With Git, for every file in your project, you can see what changed, when, and why. Git also makes it easy to revert to previous versions of files if you ever need to.
The web editor performs some Git operations behind the scenes. Understanding these concepts will help you work more effectively with the web editor and collaborate with team members who are working in their local development environments.
## Core Git concepts
## Pull requests and reviewing changes
Pull requests let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content.
* **URLs** with `?assistant=open` appended will open the assistant when the page loads. For example, [https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open).
Both methods open a chat panel on the right side of your docs. Users can ask any question and the assistant will search your documentation for an answer. If no relevant information is found, the assistant will respond that it cannot answer the question.
## 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.
### 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
# Claude Code
Source: https://mintlify.com/docs/guides/claude-code
Configure Claude Code to help write, review, and update your docs
Claude Code is an agentic command line tool that can help you maintain your documentation. It can write new content, review existing pages, and keep docs up to date.
You can train Claude Code to understand your documentation standards and workflows by adding a `CLAUDE.md` file to your project and refining it over time.
## Getting started
**Prerequisites:**
* Active Claude subscription (Pro, Max, or API access)
**Setup:**
1. Install Claude Code:
```bash
npm install -g @anthropic-ai/claude-code
```
2. Navigate to your docs directory.
3. (Optional) Add the `CLAUDE.md` file below to your project.
4. Run `claude` to start.
## CLAUDE.md template
Save a `CLAUDE.md` file at the root of your docs directory to help Claude Code understand your project. This file trains Claude Code on your documentation standards, preferences, and workflows. See [Manage Claude's memory](https://docs.anthropic.com/en/docs/claude-code/memory) in the Anthropic docs for more information.
Copy this example template or make changes for your docs specifications:
```mdx
# Mintlify documentation
## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information
## Project context
- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components
## Content strategy
- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability of information
- Make content evergreen when possible
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes
## docs.json
- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
## Frontmatter requirements for pages
- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation
## Writing standards
- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links
## Git workflow
- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks
## Do not
- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification
```
## Sample prompts
Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs.
### Convert notes to polished docs
Turn rough drafts into proper Markdown pages with components and frontmatter.
**Example prompt:**
```text wrap
Convert this text into a properly formatted MDX page: [paste your text here]
```
### Review docs for consistency
Get suggestions to improve style, formatting, and component usage.
**Example prompt:**
```text wrap
Review the files in docs/ and suggest improvements for consistency and clarity
```
### Update docs when features change
Keep documentation current when your product evolves.
**Example prompt:**
```text wrap
Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples
```
### Generate comprehensive code examples
Create multi-language examples with error handling.
**Example prompt:**
```text wrap
Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling
```
## Extending Claude Code
Beyond manually prompting Claude Code, you can integrate it with your existing workflows.
### Automation with GitHub Actions
Run Claude Code automatically when code changes to keep docs up to date. You can trigger documentation reviews on pull requests or update examples when API changes are detected.
### Multi-instance workflows
Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss.
### Team collaboration
Share your refined `CLAUDE.md` file with your team to ensure consistent documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process.
### Custom commands
Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team.
# Content Security Policy (CSP) configuration
Source: https://mintlify.com/docs/guides/csp-configuration
Domain whitelist and header configurations for reverse proxies, firewalls, and networks that enforce strict security policies
Content Security Policy (CSP) is a security standard that helps prevent cross-site scripting (XSS) attacks by controlling which resources a web page can load. Mintlify serves a default CSP that protects most sites. If you host your documentation behind a reverse proxy or firewall, that overwrites the default CSP, you may need to configure CSP headers for features to function properly.
## CSP directives
The following CSP directives are used to control which resources can be loaded:
* `script-src`: Controls which scripts can be executed
* `style-src`: Controls which stylesheets can be loaded
* `font-src`: Controls which fonts can be loaded
* `img-src`: Controls which images, icons, and logos can be loaded
* `connect-src`: Controls which URLs can be connected to for API calls and WebSocket connections
* `frame-src`: Controls which URLs can be embedded in frames or iframes
* `default-src`: Fallback for other directives when not explicitly set
## Domain whitelist
| Domain | Purpose | CSP directive | Required |
| :------------------------------ | :-------------------- | :-------------------------- | :------- |
| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS, fonts | `style-src`, `font-src` | Required |
| `*.mintlify.dev` | Documentation content | `connect-src` | Required |
| `d3gk2c5xim1je2.cloudfront.net` | Icons, images, logos | `img-src` | Required |
| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | Optional |
| `cdn.segment.com` | Segment analytics | `script-src`, `connect-src` | Optional |
| `plausible.io` | Plausible analytics | `script-src`, `connect-src` | Optional |
| `tag.clearbitscripts.com` | Clearbit tracking | `script-src` | Optional |
| `cdn.heapanalytics.com` | Heap analytics | `script-src` | Optional |
| `chat.cdn-plain.com` | Plain chat widget | `script-src` | Optional |
| `chat-assets.frontapp.com` | Front chat widget | `script-src` | Optional |
## Example CSP configuration
#### Videos
Use the HTML video element for self-hosted video content:
Embed YouTube videos using iframe elements:
#### Tooltips
Example of tooltip usage:
## 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
```
```
#### Link images
To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
```html
```
```
## Videos
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.