# 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.
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 our [Enterprise
plan](https://mintlify.com/pricing?ref=sso). Please{" "}
contact sales for more information.
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:sales@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 /docs subpath using Cloudflare Workers
To host your documentation at a `/docs` subpath 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).
## 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.
### 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 and `[YOUR_DOMAIN]` with your website's base URL.
```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 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");
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 (it can take up to a few
hours).
### 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, and `[LANDING_DOMAIN]` with your landing page URL.
```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 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");
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, which can take up to a few hours.
# AWS Route 53 and Cloudfront
Source: https://mintlify.com/docs/advanced/subpath/route53-cloudfront
Host documentation at a /docs subdirectory using AWS services
## Create Cloudfront Distribution
Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution`

For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is the project's unique subdomain. Click on `Use: [SUBDOMAIN].mintlify.dev`

For **Cache key and origin requests**, select `Caching Optimized`.

And for **Web Application Firewall (WAF)**, enable security protections

The remaining settings should be default. Click `Create distribution`.
## Add Default Origin
After creating the distribution, navigate to the `Origins` tab.

We want to find a staging URL that mirrors where the main domain (example.com). This is highly variant depending on how your landing page is hosted.
For instance, if your landing page is hosted on Webflow, you can use the
Webflow's staging URL. It would look like `.webflow.io`.
If you use Vercel, you use the `.vercel.app` domain available for every project.
If you're unsure on how to get a staging URL for your landing page, [contact
support](https://mintlify.com/docs/support) and we'd be happy to help
Once you have the staging URL, ours for instance is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app), create a new Origin and add it as the **Origin domain**.

By this point, you should have two Origins - one with `[SUBDOMAIN].mintlify.app` and another with with staging URL.
## Set Behaviors
Behaviors in Cloudfront enables control over the subpath logic. At a high level, we're looking to create the following logic.
* **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`
* **If a user lands on any other page**, go the current landing page
We're going to create three behaviors by clicking on the `Create behavior` button.
### `/docs/*`
The first behavior should have a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)

For **Cache policy**, select `CachingOptimized` and create behavior.
### `/docs`
The second behavior should be the same as the first one but with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.

### `Default (*)`
Lastly, we're going to edit the `Default (*)` behavior.

We're going to change the default behavior's **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`).

Click on `Save changes`.
## 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 `/docs` to the URL, you should see it going to the Mintlify documentation instance.
## Connecting it 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)
Navigate to [Route53](https://aws.amazon.com/route53) inside the AWS console, and click into the `Hosted zone` for your primary domain. Click on `Create record`

Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option.

Click `Create records`.
You may need to remove the existing A record if one currently exists.
And voila! You should be able to have your documentation served at `/docs` for your primary domain.
# Vercel
Source: https://mintlify.com/docs/advanced/subpath/vercel
Host documentation at a /docs subpath using Vercel
## vercel.json Configuration
To host your documentation at a custom subpath using Vercel, you need to add the
following configuration to your `vercel.json` file.
```json
{
"rewrites": [
{
"source": "/docs",
"destination": "https://[subdomain].mintlify.dev/docs"
},
{
"source": "/docs/:match*",
"destination": "https://[subdomain].mintlify.dev/docs/:match*"
}
]
}
```
For more information, you can also refer to Vercel's offical guide on
rewrites: [Project Configuration:
Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
# AI Ingestion
Source: https://mintlify.com/docs/ai-ingestion
Prepare your documentation for LLMs and AI tools
export const PreviewButton = ({children, href}) => {
return
{children}
;
};
Mintlify generates optimized formats and provides shortcuts that help users get faster, more accurate responses when using your documentation as context for LLMs and AI tools.
## Contextual menu
Provide quick access to AI-optimized content and direct integrations with popular AI tools from a contextual menu on your pages.
* **Copy page**: Copies the current page as Markdown for pasting as context into AI tools.
* **View as Markdown**: Opens the current page as Markdown.
* **Open in ChatGPT**: Creates a ChatGPT conversation with the current page as context.
* **Open in Claude**: Creates a Claude conversation with the current page as context.
### Enabling the contextual menu
Add the `contextual` field to your `docs.json` and specify which options you want to include in your menu.
```json
{
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
}
}
```
## /llms.txt
The [/llms.txt file](https://llmstxt.org) is an industry standard that helps general-purpose LLMs index more efficiently, similar to how a sitemap helps search engines.
Every documentation site automatically hosts an `/llms.txt` file at the root that lists all available pages in your documentation. AI tools can use this file to understand your documentation structure and find relevant content to user prompts.
Open llms.txt for this site
## /llms-full.txt
The `/llms-full.txt` file combines your entire documentation site into a single file as context for AI tools.
Every documentation site automatically hosts an `/llms-full.txt` file at the root.
Open llms-full.txt for this site
## Generating Markdown versions of pages
Markdown provides structured text that AI tools can process more efficiently than HTML, which results in better response times and lower token usage.
### .md extension
Add a `.md` to a page's URL to display a Markdown version of that page.
Open quickstart.md
### Command + C shortcut
Select Command + C (Ctrl + C on Windows) to copy any page as Markdown.
# 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 API documentation projects as it's more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content.
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 per page by adding `playground` at the top of the `MDX` file:
```mdx
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
```
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"
---
```
# OpenAPI Setup
Source: https://mintlify.com/docs/api-playground/openapi-setup
Reference OpenAPI endpoints in your docs pages
OpenAPI is a specification for describing REST 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/).
### 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.
## Auto-populate API pages
You can add an `openapi` field to any navigation element in your `docs.json` to auto-populate your docs with a page for each specified endpoint. The `openapi` field can contain the path to an OpenAPI document in your docs repo or the URL of a hosted OpenAPI document.
The metadata for the generated pages will have the following default values:
* `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
* `description`: The `description` field from the OpenAPI operation, if present.
* `version`: The `version` value from the anchor or tab, if present.
* `deprecated`: The `deprecated` field from the OpenAPI operation, if present. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page.
If you have some endpoints in your OpenAPI schema that you want to exclude from your auto-populated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the endpoint.
### Example with navigation tabs
```json {5}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
### Example with navigation groups
```json {8-11}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
}
]
}
]
}
```
The directory field is optional. If not specified, the files will be placed in the `api-reference` directory of the docs repo.
## Create `MDX` files for API pages
If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you can create `MDX` pages for each operation. 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.
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.
For webhooks, use `webhook` (case insensitive) instead of the HTTP method (like `GET` or `POST`) in your reference.
### 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"
---
```
# 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. You can add an `openapi` property to any navigation element to auto-populate your docs with a page for each endpoint specified in your OpenAPI document.
In this example, Mintlify will generate a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
```json
{
"navigation": [
{
"group": "API reference",
"openapi": "openapi.json"
}
]
}
```
## 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 `MDX` pages
When you need more control over your API documentation, create individual `MDX` pages for your endpoints. This allows you to:
* Customize page metadata
* Add additional content like examples
* Hide specific operations
* Reorder pages in your navigation
See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints.
## 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
`/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 `/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 [here](settings#api-configurations). This will
likely require you to configure CORS on your server, as these requests will now come directly
from your users' browsers.
# Create Assistant Chat Topic
Source: https://mintlify.com/docs/api-reference/chat/create-topic
POST /chat/topic
Creates a topic to manage message history for a given AI assistant conversation
# Create Assistant Chat Message
Source: https://mintlify.com/docs/api-reference/chat/generate-message
POST /chat/message
Generate a completion in response to a user query
# Introduction
Source: https://mintlify.com/docs/api-reference/introduction
## Trigger Updates
You can leverage the REST API to programmatically trigger an update when desired.
## Authentication
You can generate an API key through
[the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). The API key is
associated with the entire org and can be used across multiple deployments.
## Admin API key
The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](/api-reference/update/trigger).
## Assistant API key
The Assistant API allows you to embed the AI assistant experience grounded in your docs and continually kept up to date into any application of your choosing.
Responses include citations so you can point your users to the right places they need to get help.
The Assistant API token is a public token that can be referenced in your
frontend code whereas the API key is a server-side token that should be kept
secret.
Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use
the API for AI assistant. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
# 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
Guarantee privacy of your docs by authenticating users
Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method.
**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options.
Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). Please{" "}
contact sales for more information.
## Configuring authentication
Select the handshake method that you want to configure.
### 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 [Sending Data](/authentication-personalization/sending-data) 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.
### Prerequisites
* An OAuth 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. 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.
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 [Sending Data](/authentication-personalization/sending-data) 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**: `['docs-user-info']`
* **Token URL**: `https://auth.foo.com/exchange`
* **Info API URL**: `https://api.foo.com/docs/user-info`
**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope, and returns:
```json
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configure your OAuth server to allow redirects** to your callback URL.
### 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.
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!
# Overview
Source: https://mintlify.com/docs/authentication-personalization/overview
Control who sees your documentation and customize their experience
Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). Please{" "}
contact sales for more information.
There are three approaches to manage access and customize your documentation based on user information.
* **Authentication**: Complete privacy protection for all content with full content customization.
* **Partial authentication**: Page-by-page access control with full content customization.
* **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible.
**Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features.
**Choose partial authentication** if you want some pages to be public and others private.
**Choose personalization** if you want to customize content based on user information and your documentation can be publicly accessible.
## Handshake methods
Authentication and personalization offer multiple handshake methods for controlling access to your content.
### Available for all methods
**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow.
* Pros of JWT:
* Reduced risk of API endpoint abuse.
* No CORS configuration.
* No restrictions on API URLs.
* Cons of JWT:
* Must be compatible with your existing login flow.
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
* When you refresh user data, users must log into your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs.
**OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers.
* Pros of OAuth 2.0:
* Heightened security standard.
* No restrictions on API URLs.
* Cons of OAuth 2.0:
* Requires significant work if setting up an OAuth server for the first time.
* Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately.
### Available for authentication and partial authentication
**Mintlify dashboard**: Allow all of your dashboard users to access your docs.
* Pros of Mintlify dashboard:
* No configuration required.
* Enables private preview deployments, restricting access to authenticated users only.
* Cons of Mintlify dashboard:
* Requires all users of your docs to have an account in your Mintlify dashboard.
**Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization.
* Pros of password:
* Simple setup with no configuration required to add new users, just share the password.
* Cons of password:
* Lose personalization features since there is no way to differentiate users with the same password.
* Must change the password to revoke access.
### Available for personalization
**Shared session**: Use the same session token as your dashboard to personalize content.
* Pros of shared session:
* Users that are logged into your dashboard are automatically logged into your docs.
* User sessions are persistent so you can refresh data without requiring a new login.
* Minimal setup.
* Cons of shared session:
* Your docs will make a request to your backend.
* You must have a dashboard that uses session authentication.
* CORS configuration is generally required.
## Content customization
All three methods allow you to customize content with these features.
### Dynamic `MDX` content
Display dynamic content based on user information like name, plan, or organization.
The `user` variable contains information sent to your docs from logged in users. See [Sending data](/authentication-personalization/sending-data) for more information.
**Example**: Hello, {user.name ?? 'reader'}!
```jsx
Hello, {user.name ?? 'reader'}!
```
This feature is more powerful when you pair it with custom data about your users. For example, you can give different instructions based on a user's plan.
**Example**: 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. To speak to our team about upgrading, contact our sales team.>
: <>To request this feature for your enterprise org, contact our team.>
}
```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. To speak to our team about upgrading, contact our sales team.>
: <>To request this feature for your enterprise org, contact our team.>
}
```
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}`.
### 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.
### 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"]
---
```
# Partial Authentication Setup
Source: https://mintlify.com/docs/authentication-personalization/partial-authentication-setup
Control access to specific pages
Partial authentication lets you protect private documentation while keeping other pages publicly viewable. Users can browse public content freely and authenticate only when accessing protected pages.
Partial authentication shares all the same features as authentication, but with the ability to allow unauthenticated users to view certain pages.
## Setup
Follow the [Authentication Setup](/authentication-personalization/authentication-setup) guide and select **Partial Authentication** when configuring your chosen handshake method.
## Making pages public
By default, all pages are protected. Add the `public` property to the page's frontmatter to make it viewable without authentication:
```mdx
---
title: "My Page"
public: true
---
```
# Personalization Setup
Source: https://mintlify.com/docs/authentication-personalization/personalization-setup
Let users log in for customized documentation experiences
Personalization lets you customize your documentation based on user information. This guide covers setup for each available handshake method.
**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options.
## 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 [Sending Data](/authentication-personalization/sending-data) 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 [Sending Data](/authentication-personalization/sending-data) 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. 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 `docs-user-info` 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 [Sending Data](/authentication-personalization/sending-data))
* 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.
# Sending Data
Source: https://mintlify.com/docs/authentication-personalization/sending-data
User data format for personalizing your documentation
When implementing authentication or 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.
## User data format
```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).
A list of groups that the user belongs to. Pages with a matching `groups` field in their metadata will be 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.
**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...
User-specific values that will be prefilled in the API playground if supplied. Save users time when testing your APIs with their own data.
**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"
}
}
}
```
# Product Updates
Source: https://mintlify.com/docs/changelog
New updates and improvements
## API playground stability updates
* Search to find an endpoint
* Indicate a deprecated endpoint with a tag
* Hide auto-generated API pages from navigation
* Upload multipart or form data files
Learn more at [API playground docs.](/api-playground/)
## `mint update`
Can now use `mint update` to update your CLI.
## Web Editor 3.0

Overhauled usability in the WYSIWYG editor.
**Major improvements**
* Search for file names using ⌘ + P shortcut
* Pages load 10x faster
* Faster load times when searching for a branch
* Page options tab to configure layout, title, & metadata for SEO
* Floating toolbar when you highlight text
**Additional fixes**
* Fixed top margin for changelog components
* Improved reliability of right click behavior
* After clicking publish, you’ll stay on the same page instead of being brought to an empty state
* Standardized colors in file icons
* Improved reliability after selecting new branches several times in a row
* Removed Diff mode
* More consistency when creating a new folder from the dropdown
* Fixed block quotes creating more block quotes when trying to deselect
## AI Translations in beta

Translate all of your documentation with AI. [Learn more.](navigation#localization)
## Export docs to PDF in beta
Export all of your documentation, a subdirectory, or a singe page as a PDF.
## React hook support
Bring interactivity to your docs. All standard React hooks are automatically available in your MDX files. [Learn more.](react-components)
## MCP server generator

Generate MCP servers so that AI applications can interact with your docs or APIs. Written content is automatically generated as an MCP server, and you can generate an MCP server from your OpenAPI spec with one click.
Check out [docs on getting started with MCP.](/mcp)
## Improvements
* Tag changelog updates so end users can filter updates
* Sonnet-3.7 supported for AI Chat. Configure your preferred model through the dashboard
* Change your deployment name directly in dashboard settings
## Bug fixes
* OG images fixed
* Fixed icon style inconsistency for anchors without container
* Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness
* Show code examples even when in simple mode for API playground
* Support "command + k" shortcut for search in web editor
* Codeblocks within callouts expand to fill the width of the callout area
## New configuration schema `docs.json`

We've introduced a new `docs.json` schema as a replacement for `mint.json`, to support better multi-level versioning, easier visual comprehension, and more consistent terminology. For more information on what's changed, [check out our blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json).
Upgrade from `mint.json` to `docs.json` with the following steps:
1. Make sure your CLI is the latest version
```bash
npm i mint@latest -g
```
1. In your docs repository, run
```bash
mint upgrade
```
1. Delete your old mint.json file and push your changes
## CI Checks
Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci).
## .md support for LLMs
All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation.
## More Themes

New [pre-built themes](themes) to modify the look & feel of your docs. Configure via your [docs.json file](settings).
Now available:
* Maple
* Palm
* Willow
## Other improvements
* [Guide to Technical Writing:](https://mintlify.com/guides/introduction)Best practices for writing technical documentation, including audience research, content types, and writing tips.
* [Dropdown component](navigation#dropdowns): Organize navigation with a dropdown, in addition to tabs and anchors.
* [AI syntax fixer](https://x.com/ricardonunez_io/status/1892334887644123192): The web editor will catch if there’s a parsing error and use AI to suggest fixes.
## AI Assistant Improvements
* New UI with dedicated chat page & pre-filled prompts
* Stability improvements, e.g. bug fixes of editing the wrong file or no files at all
* More robust knowledge for adding & editing components
* Improved mint.json file editing
## Partial Authentication
Customize access to any page or section of content depending on user permissions. Supports connecting with your own authentication system.
## Revamped API Playground
We’ve overhauled the design and performance of the [API Playground](/api-playground/). Updates include:
* Easier detail expansion for an overview of a field
* More intuitive nested design, e.g. adding or deleting items
* Faster response times
## Quality Improvements
* Support for requiring authentication to access preview deployments
## Authentication

Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs.
## AI Assistant

You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request.
## GitLab Integration Upgrade
We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started.
## Web Editor

We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown.
Check out our [docs on getting started with Web Editor](/editor).
## /llms.txt support

All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org)
## Localization
You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale.
### Quality Improvements
* Return chat & search results based on the current version that the user is reading
* Authenticate users with OAuth, in addition to JWT or Shared Session tokens.
## Changelogs
Launched a new [Update component](/components/update) to make it easier to display and report updates (like this one) to your users.

## Code Line Highlighting
You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
```javascript Line Highlighting Example {1,3-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````mdx
```javascript Line Highlighting Example {1,3-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
## Light mode code blocks
Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`:
```json
"codeBlock": {
"mode": "auto"
}
```
## Advanced Footer

You can now add more links to the standard footer. This upgrade
provides more consistency between landing pages and docs, or greater customization
if you want to spotlight specific pages like socials or status logs.
## Filter search based on the current user
When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
## Custom Prompts for AI Chat
You can now customize the prompts for the AI chat. Please reach out to [support](mailto:sales@mintlify.com) if you'd like to customize the prompts.
## Dashboard Improvements
* Added ability to change custom domain to be /docs directly through dashboard settings.
* Consolidated the login and signup pages to decrease friction and confusion.
* Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them.
* Added login with Google OAuth
* Added ability to add new deployment through dashboard settings.
## Bug Fixes
* Can now use leading slashes in navigation.
* Can now edit CSS & JS files in the web editor.
* Fixed `suggestEdit` not showing up even when enabled.
* Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results.
* Don't allow search engines to crawl user-auth protected pages.
* Revalidate the cache when an org is deleted.
* We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages.
* Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions.
* Add in-line-style support for icons
* Fixed the pop-in of custom CSS in docs.
* Properly show in-line code styling in conjunction with links.
* Maintain scroll position when you click the back button in a browser.
## Custom Fonts

Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand.
## Images in Card components
Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](/components/cards#image-card).
## Update Speed Performances

For large projects (\~3,000 files), the download step for docs updates is now
\~440x faster - a 99.8% time reduction. Across the board, file downloads during
updates are now \~5.5x faster - an 81.8% time reduction.
## SEO improvements

We've fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements.
## Dashboard Improvements
* App router migration in the dashboard.
* Search analytics are now available in the dashboard.
* Delete an org functionality has been added to the dashboard.
* Shipped GitLab connection UI.
* Fix incorrect analytics data.
* Add-on's can now be directly purchased through the dashboard.
## Bug Fixes
* Fixed a bug where the top bar would not stretch to the width of the screen when it's in custom mode and the sidebar layout is `sidenav`.
* Fix relative positioning of the AI widget.
## More
* **Troubleshooting for API pages**: API pages could be complicated so we listed
common issues to help you sort them out quickly —
[Read the docs](/api-playground/troubleshooting)
## OpenAPI Reference Pages
* Endpoints defined by OpenAPI that are complex and recursive are now 98%
smaller.
* We now show
[additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/)
in OpenAPI pages.
## File Uploads in API Playground
By default, API playground requests are proxied by Mintlify. Now you can use
`disableProxy` to disable this behavior and support request types like file
uploads.
* [Learn more about API configurations](settings#api-configurations)
## Mobile SEO improvements
We've fixed the mobile layout of our docs so that they are more SEO-friendly -
including adding proper aria tags to elements.
## Support Form
We added a more detailed support form to the Mintlify dashboard. You can now
submit a form to get in touch with us.
## Bug Fixes
* Fixed a bug for the Segment integration functionality.
* We now raise more granular error messages for GitHub permissions when
interacting with the editor.
* Fixed bugs where the navigation would not properly expand when a direct link
was used.
## AI Widget

For `Pro` users, we introduced Mintlify Widget, an extension of your docs to
answer your users' questions when and where they asked. You can add this
AI-powered chatbot to any web page: your landing page, inside your product, or
on your existing documentation pages.
* [Read the blog announcement](https://mintlify.com/blog/widget)
## Pro Plan
We also updated our pricing plans for better customizability and scale.
* [Read the blog announcement](https://mintlify.com/blog/pro-plan)
## API Playground Code Example Sync
When you browse API docs, the selected code example now syncs across your pages.
## Insights
Currently in beta, this feature summarizes common user questions and patterns
into easy-to-digest reports with AI-powered suggestions on how to improve your
product.
## Launch Week Highlights
* Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling.
* Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated search bar UI.
* Web Editor branching: create branches in our web editor without an IDE.
* User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers.
* OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json.
## Okta SSO
We now support sign-on via Okta SAML and OIDC.
## Mintlify REST API
Programmatically rigger updates to your documentation.
## Custom mode
Add a configuration to the metadata to remove all elements except for the top bar.
Example use cases:
* Create a custom global landing page setup with custom components
* Add full-screen videos or image galleries
* Embed custom iFrame demo elements to add intractability to your docs
Check out our [Custom Mode docs](pages#custom-mode).
## Mintlify MDX for VSCode
Call snippets of our pre-built components and callouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets).
## Quality Improvements
* Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments
* Versioning with tabs fully supported
* Wildcard redirects now supported
* CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development
## Launch Week Highlights
* Preview Deployments: When you create a pull request, we'll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates.
* Snippets V2: We now support fully reusable components and variables for snippets.
* Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome.
* AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears.
# 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. 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 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. You can use [FontAwesome](https://fontawesome.com/icons) icons, [Lucide](https://lucide.dev/icons/) icons, or absolute URLs.
```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();
```
````
# Accordions
Source: https://mintlify.com/docs/components/accordions
A dropdown component to toggle content visibility
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!");
}
}
```
````
````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!");
}
}
```
Check out the [Accordion](/components/accordions) docs for all the supported props.
Check out the [Accordion](/components/accordions) docs for all the supported props.
Check out the [Accordion](/components/accordions) docs for all the supported props.
````
### Props
Title in the Accordion preview.
Detail below the title in the Accordion preview.
Whether the Accordion is open by default.
A [Font Awesome icon](https://fontawesome.com/icons), [Lucide
icon](https://lucide.dev/icons), or SVG code
One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or
"brands"
## Accordion Groups
You can group multiple accordions into a single display. Simply add `` around your existing `` components.
You can put other components inside Accordions.
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
Check out the [Accordion](/components/accordions) docs for all the supported props.
Check out the [Accordion](/components/accordions) docs for all the supported props.
Check out the [Accordion](/components/accordions) docs for all the supported props.
# 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, or Check:
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
```jsx
This is a danger callout
```
```mdx Callout Example
This adds a note in the content
```
# Cards
Source: https://mintlify.com/docs/components/cards
Highlight main points or links with customizable icons
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.
```
```mdx Image Card Example
Here is an example of a card with an image
```
## Horizontal card
Add a `horizontal` property to display cards horizontally.
Here is an example of a horizontal card
## Image card
Add an `img` property to display an image on the top of the card.
Here is an example of a card with an image
## Link card
You can customize the CTA and whether or not to display the arrow on the card. By default, the arrow will only show for external links.
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.
```
## Grouping cards
You can group cards in [columns](/components/columns).
This is the first card.
This is the second card.
## Props
The title of the card
A [Font Awesome icon](https://fontawesome.com/icons), [Lucide
icon](https://lucide.dev/icons), or JSX compatible SVG code in `icon={}`.
To generate JSX compatible SVG code:
1. Use the [SVGR converter](https://react-svgr.com/playground/).
2. Copy the code inside the `` tag.
3. Paste the code into your card. Make sure to only copy and paste the code inside the `` tag.
4. You may need to decrease the height and width to make the image fit.
One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
The color of the icon as a hex code
The url that clicking on the card would navigate the user to
Makes the card more compact and horizontal
The url or local path to an image to display on the top of the card
Label for the action button
Enable or disable the link arrow icon
# Code Groups
Source: https://mintlify.com/docs/components/code-groups
The CodeGroup component lets you combine code blocks in a display separated by tabs
You will need to make [Code Blocks](/code) then add the `` component around them. Every Code Block must have a filename because we use the names for the tab buttons.
See below for an example of the end result.
```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 Code Group Example
```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 multiple cards in a grid, by specifying the number of grid columns.
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit
```mdx Card Group Example
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit
```
### Props
The number of columns per row
# Examples
Source: https://mintlify.com/docs/components/examples
Display code blocks at the top-right of the page on desktop devices
The `` and `` stick code blocks to the top-right of a page even as you scroll. The components work on all pages even if you don't use an API playground.
`` and `` show up like regular code blocks on mobile.
## Request Example
The `` component works similar to [CodeGroup](/components/code-groups), but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside ``.
Please set a name on every code block you put inside RequestExample.
````mdx RequestExample Example
```bash Request
curl --request POST \
--url https://dog-api.kinduff.com/api/facts
```
````
## Response Example
The `` component is the same as `` but will show up underneath it.
````mdx ResponseExample Example
```json Response
{ "status": "success" }
```
````
# Expandables
Source: https://mintlify.com/docs/components/expandables
Toggle to display nested properties.
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
```
## Props
The name of the object you are showing. Used to generate the "Show NAME" and
"Hide NAME" text.
Set to true to show the component as open when the page loads.
# Fields
Source: https://mintlify.com/docs/components/fields
Set parameters for your API or SDK references
There are two types of fields: Parameter Fields and Response Fields.
## Parameter Field
A `ParamField` component is used to define the parameters for your APIs or SDKs. Adding a `ParamField` will automatically add an [API Playground](/api-playground/overview).
An example of a parameter field
```mdx Path Example
An example of a parameter field
```
```mdx Body Example
The age of the user. Cannot be less than 0
```
```mdx Response Example
A response field example
```
### Props
Whether it is a query, path, body, or header parameter followed by the name
Expected type of the parameter's value
Supports `number`, `string`, `bool`, `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 used by the server if the request does not provide a value
Value that will be used to initialize the playground
Placeholder text for the input in the playground
Description of the parameter (markdown enabled)
## Response Field
The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something.
A response field example
```mdx
A response field example
```
### Props
The name of the response value.
Expected type of the response value - this can be any arbitrary string.
The default value.
Show "required" beside the field name.
Whether a field is deprecated or not.
Labels that are shown before the name of the field
Labels that are shown after the name of the field
# Frames
Source: https://mintlify.com/docs/components/frames
Use the Frame component to wrap images or other components in a container.
Frames are very helpful if you want to center an image.
## Captions
You can add additional context to an image using the optional `caption` prop.
## Props
Optional caption text to show centered under your component.
```mdx Frame
```
```mdx Frame with Captions
```
# Icons
Source: https://mintlify.com/docs/components/icons
Use icons from popular icon libraries
```mdx Icon Example
```
## Inline Icons
The icon will be placed inline when used in a paragraph.
```markdown Inline Icon Example
The documentation you want, effortlessly.
```
The documentation you want, effortlessly.
### Props
A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon.
One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons).
The color of the icon as a hex code (e.g., `#FF5733`)
The size of the icon in pixels
# Mermaid
Source: https://mintlify.com/docs/components/mermaid-diagrams
Display diagrams using Mermaid
````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
```
````
[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code.
```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
```
For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/).
## Syntax for Mermaid diagrams
To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block.
````mdx
```mermaid
// Your mermaid code block 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
Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired.
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 Props
A list of `Step` components.
The size of the step titles. One of `p`, `h2` and `h3`.
## Individual Step Props
The content of a step either as plain text, or components.
A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}`
One of `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
You can add any number of tabs, and other components inside of tabs.
☝️ Welcome to the content that you can only see inside the first Tab.
You can add any number of components inside of tabs.
```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.
💪 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.
```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.
💪 Here's content that's only inside the third Tab.
````
## Tab Props
The title of the tab. Short titles are easier to navigate.
# Tooltips
Source: https://mintlify.com/docs/components/tooltips
Show a definition when you hover over text
Tooltips are a way to show a definition when you hover over text.
Hover over me and see a tooltip in action
```mdx Tooltip Example
Hover over me
```
# Update
Source: https://mintlify.com/docs/components/update
Keep track of changes and updates
The `Update` component is used to keep track of changes and updates.
## Changelog
You can add anything here, like a screenshot, a code snippet, or a list of changes.
#### Features
* Responsive design
* Sticky section for each changelog
### How to use
```mdx
This is how you use a changelog with a label
and a description.
This is how you use a changelog with a label
and a description.
```
You can use multiple `Update` components to create changelogs.
Each `label` creates an anchor and also shows up on the table of contents on the right.
## Props
The label give to the update, appears as sticky text to the left of the changelog.
Tags for the changelog, will be shown as filters in the right side panel.
Description of the update, appears below the label and tag.
```mdx Update Example
This is how you use a changelog with a label
and a description.
```
# 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).
# Web Editor
Source: https://mintlify.com/docs/editor
Build your documentation using the Mintlify web editor
## Introduction
The web editor is a visual interface for creating, editing, and reviewing documentation directly in your browser.
The web editor offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience while maintaining synchronization with your Git repository, which lets you see updates in real time and collaborate with your team on documentation changes.
### Web editor vs. CLI
The web editor lets you write and edit your documentation in your browser without requiring local development tools or using the command line. You should use the web editor if you want to maintain your documentation in one place with one tool.
The CLI is a command line tool that allows you to create and manage your documentation locally using the IDE of your choice. You should use the CLI if you want to integrate documentation into your existing development workflow.
Both the web editor and CLI are fully integrated with your Git repository, so you can use them interchangeably and different members of your team can use either tool based on their preferences.
## Editor Modes
The web editor offers two modes to accommodate different editing preferences and needs.
You can switch between natural modes at any time using the toggle in the top right corner of the editor toolbar.
### 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.
#### Component Menu
You can add content blocks and other components to your documentation in visual mode using the dropdown component menu.
1. Press the `/` key to open the component menu.
2. Select a component from the menu.
### Markdown Mode
Markdown mode provides direct access to the underlying MDX code of your documentation. This mode is preferable when you need precise control over component properties or when you prefer to write in Markdown/MDX syntax.
## Making Changes
1. **Browse files**: Use the sidebar file explorer to navigate through your documentation.
2. **Open a file**: Click on the file that you want to edit to open it in the editor.
3. **Make changes**: Edit the content using visual or Markdown mode. Changes are automatically saved as drafts.
4. **Preview changes**: See how your changes will appear in visual mode.
## Publishing
The **Publish** button works differently depending on your branch:
* **Deployment branch**: Updates your live site immediately. This is usually the `main` branch.
* **Other branches**: Creates a pull request for review.
## Branches
Branches allow you to safely work on changes without affecting your live documentation. When your changes are ready, you can merge them into your deployment branch with a pull request.
Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
### 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.
4. Select **Create Branch**.
### Switching Branches
1. Select the current branch name in the editor toolbar.
2. Select the branch that you want to switch to from the dropdown menu.
### 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.
When you are working on a branch, your changes are not automatically saved.
## Pull Requests
Pull requests (or PRs) let you and other people review changes that you've made on a branch and then merge those changes into your documentation.
### Creating a Pull Request on a Branch
1. Make your changes on a branch.
2. Click the **Publish Pull Request** button in the top-right corner of the editor.
3. Add a Pull Request Title and Description for your pull request. A good title and description will help reviewers understand the changes you've made.
4. Click **Publish Pull Request**.
### Reviewing Pull Requests
You can review pull requests in your Git platform (GitHub, GitLab).
After you create a pull request, you can see a preview deployment of the changes.
After a reviewer approves a pull request, you can merge it to deploy the changes to your live documentation site.
## Git Synchronization
The web editor integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
### How Git Sync Works
* **Authentication**: The web editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
* **Automatic fetching**: When you open the editor, it automatically fetches the latest content from your repository's deployment branch.
* **Change tracking**: As you make edits, the web editor tracks changes and can commit them to your repository.
* **Branching**: You can make changes directly to your deployment branch or to a separate branch, depending on your workflow preferences.
* **Pull requests**: For collaborative workflows, you can create pull requests from the web editor.
## Git Terminology
Understanding the following terms can help you work more effectively with the web editor and the Git workflow.
A repository (or repo) is where your documentation files are stored, along with their revision history. The web editor connects to your Git repository to fetch and store documentation content.
A commit is a snapshot of changes to your documentation at a specific point in time. When you publish changes in the web editor, you're creating a commit in your Git repository.
A branch is a parallel version of your documentation that allows you to work on changes without affecting the live version. The web editor allows you to create and switch between branches.
A pull request (or PR) is a proposal to merge changes from one branch into another, typically from a feature branch into the main branch. PRs facilitate review and discussion before changes are incorporated.
A diff (or difference) shows the specific changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified.
## Troubleshooting
Here are solutions to common issues you might encounter with the web editor.
**Possible causes:**
* Deployment is still in progress
* Caching issues in your browser
**Solutions:**
1. Check deployment status in your Mintlify Dashboard.
2. Try hard refreshing 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 and try again.
3. Contact support if the issue persists.
# 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 for frequently used Mintlify components and 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 your `.cursor/rules` directory.
````
---
description: Mintlify writing assistant guidelines
type: always
---
# Mintlify technical writing assistant
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
- 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
- End sections with next steps or related information
- Use descriptive, keyword-rich headings for navigation and SEO
### 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
- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options
## Mintlify component reference
### 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
```javascript config.js
const apiConfig = {
baseURL: 'https://api.example.com',
timeout: 5000,
headers: {
'Authorization': `Bearer ${process.env.API_TOKEN}`
}
};
```
#### Code group with multiple languages
```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
```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
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
```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
- **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' }
};
```
### API documentation components
#### Parameter fields
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
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
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.
### Interactive components
#### Cards for navigation
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.
### Media and advanced components
#### Frames for images
Wrap all images in frames.
#### Tooltips and updates
API
## 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
### 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
## AI assistant instructions
### Component selection logic
- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions
- Use **Tabs** for platform-specific content or alternative approaches
- Use **CodeGroup** when showing the same concept in multiple languages
- Use **Accordions** for supplementary information that might interrupt flow
- Use **Cards and CardGroup** for navigation, feature overviews, and related resources
- 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
### Quality assurance checklist
- Verify all code examples are syntactically correct and executable
- Test all links to ensure they are functional and lead to relevant content
- Validate Mintlify component syntax with all required properties
- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections
- Ensure content flows logically from basic concepts to advanced topics
- Check for consistency in terminology, formatting, and component usage
### Error prevention strategies
- Always include realistic error handling in code examples
- Provide dedicated troubleshooting sections for complex procedures
- Explain prerequisites clearly before beginning instructions
- Include verification and testing steps with expected outcomes
- Add appropriate warnings for destructive or security-sensitive actions
- Validate all technical information through testing before publication
````
# 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.
# 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.
Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages.
## Search, SEO, and AI context
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 existing provider
You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify.
We currently support automated migration for:
}
horizontal
/>
}
horizontal
/>
Don't see your docs provider or have a home grown system? We can still help! Please [contact support](https://mintlify.com/docs/support).
## Commands
* `mintlify-scrape section [url]` - Scrapes multiple pages in a site.
* `mintlify-scrape page [url]` - Scrapes a single page in a site.
The commands will automatically detect the framework.
## Installation
First, install the package:
```bash
npm i @mintlify/scraping
```
One-time use:
```bash Section
npx @mintlify/scraping@latest section [url]
```
```bash Page
npx @mintlify/scraping@latest page [url]
```
Global installation:
```bash
npm install @mintlify/scraping@latest -g
```
Global usage:
```bash Section
mintlify-scrape section [url]
```
```bash Page
mintlify-scrape page [url]
```
Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint.
```bash
mintlify-scrape openapi-file [openApiFilename]
-w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true]
-o, --outDir The folder in which to write any created frontmatter files [string]
```
# 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**.
# Images and Embeds
Source: https://mintlify.com/docs/image-embeds
Add image, video, and other HTML elements
## Image
Images are the most common way to add visual content to your documentation.
### Basics
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```mdx

```
To make sure images are displayed correctly in production, add a forward slash to the image path (e.g. `/path/image.jpg`).
Note that the image file size must be less than 20MB. Otherwise, we recommend hosting on a CDN provider like [S3](https://aws.amazon.com/s3), [Cloudinary](https://cloudinary.com) or a similar service.
### Embeds
To get more customizability with images, you can also use embeds to add images.
```html
```
### Disable Image Zoom
To disable the default zoom on click for images, add the `noZoom` property to image embeds.
```html
```
### Linking Images
To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor.
```html
```
### Dark Mode
To use separate images for light and dark mode, use Tailwind CSS to hide and show images.
```html
```
### Related
For more information, we recommend the following sections:
Read the reference for the Frame component
## Videos
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
For YouTube videos use:
```html
```
For other videos, use:
```html
```
To autoplay the video, use:
```html
```
Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to
be written in camelCase such as `autoPlay` and `playsInline`.
## iFrames
Loads another HTML page within the document.
```html
```
# Introduction
Source: https://mintlify.com/docs/index
Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers.
export const HeroCard = ({filename, title, description, href}) => {
return
Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers.
# CLI
Source: https://mintlify.com/docs/installation
Install the CLI to preview and develop your docs locally
## Installing the CLI
**Prerequisite**: Please install [Node.js](https://nodejs.org/en) (version 19 or higher) before proceeding.
Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
```bash npm
npm i -g mint
```
```bash yarn
yarn global add mint
```
```bash pnpm
pnpm add -g mint
```
Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:
```bash
mint dev
```
A local preview of your documentation will be available at `http://localhost:3000`.
Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
```bash npm
npx mint dev
```
```bash yarn
yarn dlx mint dev
```
```bash pnpm
pnpm dlx mint dev
```
## Updates
If your local preview is out of sync with what you see on the web in the production version, update your local CLI:
```bash
mint update
```
If this `mint update` command is not available on your local version, re-install the CLI with the latest version:
```bash npm
npm i -g mint@latest
```
```bash yarn
yarn global upgrade mint
```
```bash pnpm
pnpm up --global mint
```
## Custom ports
By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:
```bash
mint dev --port 3333
```
If you attempt to run on a port that is already in use, it will use the next available port:
```mdx
Port 3000 is already in use. Trying 3001 instead.
```
## Additional commands
While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.
### Finding broken links
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
```bash
mint broken-links
```
### Checking OpenAPI spec
You can use the CLI to check your OpenAPI file for errors using the following command:
```bash
mint openapi-check
```
You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`).
### Renaming files
You can rename and update all references to files using the following command:
```bash
mint rename
```
## Formatting
While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
If you use Cursor, Windsurf, or VSCode, we recommend the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.
## Troubleshooting
This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of the mint CLI: `npm remove -g mint`
2. Upgrade to Node v19 or higher.
3. Reinstall the mint CLI: `npm install -g mint`
Solution: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
# Amplitude
Source: https://mintlify.com/docs/integrations/analytics/amplitude
Add the following to your `docs.json` file to send analytics to Amplitude.
```json Analytics options in docs.json
"integrations": {
"amplitude": {
"apiKey": "required"
}
}
```
```json Example
"integrations": {
"amplitude": {
"apiKey": "76bb138bf3fbf58186XXX00000"
}
}
```
# Clearbit
Source: https://mintlify.com/docs/integrations/analytics/clearbit
Add the following to your `docs.json` file to send analytics to Clearbit.
```json Analytics options in docs.json
"integrations": {
"clearbit": {
"publicApiKey": "required"
}
}
```
```json Example
"integrations": {
"clearbit": {
"publicApiKey": "pk_1a1882"
}
}
```
# Fathom
Source: https://mintlify.com/docs/integrations/analytics/fathom
Add the following to your `docs.json` file to send analytics to Fathom.
You can get the `siteId` from your script settings.
```json Analytics options in docs.json
"integrations": {
"fathom": {
"siteId": "required"
}
}
```
```json Example
"integrations": {
"fathom": {
"siteId": "YSVMSDAY"
}
}
```
# Google Analytics 4
Source: https://mintlify.com/docs/integrations/analytics/google-analytics
You will need to generate a new GA4 property to use with Mintlify. The data collected will go into the same project as your other Google Analytics data.
If you are using the old version of Google Analytics, Universal Analytics, you will still be able to generate a GA4 property. GA4 data is slightly different from UA data but still gets collected in the same project.
## How to Connect GA4 to Mintlify
### Create a Web Stream
You will need to create a web stream to get the Measurement ID to put into Mintlify.
Click the cog at the bottom left of the Google Analytics screen. Then click on Data Streams.

Create a Web Stream and put the URL of your Mintlify docs site as the stream URL.
Your Measurement ID looks like `G-XXXXXXX` and will show up under Stream Details immediately after you create the Web Stream.
### Put Measurement ID in docs.json
Add your Measurement ID to your `docs.json` file like so:
```json docs.json
"integrations": {
"ga4": {
"measurementId": "G-XXXXXXX"
}
}
```
### Wait
Google Analytics takes two to three days to show your data.
You can use the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to check analytics are enabled correctly. The extension will log to your browser's console every time GA4 makes a request.
Preview links have analytics turned off.
# Google Tag Manager
Source: https://mintlify.com/docs/integrations/analytics/google-tag-manager
Add your tag ID to `docs.json` file and we'll inject the Google Tag Manager script to all your pages.
You are responsible for setting up cookie consent banners with Google Tag Manager if you need them.
```json Analytics options in docs.json
"integrations": {
"gtm": {
"tagId": "required"
}
}
```
```json Example
"integrations": {
"gtm": {
"tagId": "GTM-MGBL4PW"
}
}
```
# Heap
Source: https://mintlify.com/docs/integrations/analytics/heap
Add the following to your `docs.json` file to send analytics to Heap.
```json Analytics options in docs.json
"integrations": {
"heap": {
"appId": "required"
}
}
```
```json Example
"integrations": {
"heap": {
"appId": "1234567890"
}
}
```
# HotJar
Source: https://mintlify.com/docs/integrations/analytics/hotjar
Add the following to your `docs.json` file to send analytics to HotJar.
```json Analytics options in docs.json
"integrations": {
"hotjar": {
"hjid": "required",
"hjsv": "required"
}
}
```
# Koala
Source: https://mintlify.com/docs/integrations/analytics/koala
Add the following to your `docs.json` file to send analytics to Koala.
```json Analytics options in docs.json
"integrations": {
"koala": {
"publicApiKey": "required"
}
}
```
```json Example
"integrations": {
"koala": {
"publicApiKey": "pk_1a1882"
}
}
```
# LogRocket
Source: https://mintlify.com/docs/integrations/analytics/logrocket
Add the following to your `docs.json` file to send analytics to LogRocket.
```json Analytics options in docs.json
"integrations": {
"logrocket": {
"apiKey": "required"
}
}
```
# Mixpanel
Source: https://mintlify.com/docs/integrations/analytics/mixpanel
Add the following to your `docs.json` file to send analytics to Mixpanel.
```json Analytics options in docs.json
"integrations": {
"mixpanel": {
"projectToken": "required"
}
}
```
# Analytics Integrations
Source: https://mintlify.com/docs/integrations/analytics/overview
Integrate with an analytics platform to track events
Automatically send data about your documentation engagement to your third party analytics provider.
## All integrations
}
/>
}
/>
}
/>
}
/>
}
/>
}
/>
}
/>
}
/>
>
}
/>
}
/>
}
/>
}
/>
}
/>
}
/>
## Enabling analytics
Set your analytics keys in `docs.json`. You can add an unlimited number of analytics integrations for free.
The syntax for `docs.json` is below. You only need to include entries for the platforms you want to connect.
```json Analytics options in docs.json
"integrations": {
"amplitude": {
"apiKey": "required"
},
"clearbit": {
"publicApiKey": "required"
},
"cookies": {
"key": "required",
"value": "required"
},
"fathom": {
"siteId": "required"
},
"ga4": {
"measurementId": "required"
},
"gtm": {
"tagId": "required"
},
"hotjar": {
"hjid": "required",
"hjsv": "required"
},
"koala": {
"publicApiKey": "required"
},
"logrocket": {
"appId": "required"
},
"mixpanel": {
"projectToken": "required"
},
"pirsch": {
"id": "required"
},
"plausible": {
"domain": "required"
},
"posthog": {
"apiKey": "required",
"apiHost": "optional"
},
"segment": {
"key": "required"
},
"telemetry": {
"enabled": "boolean"
}
}
```
## Analytics events
We send the following events to your analytics provider.
| Event name | Description |
| :-------------------------------- | :--------------------------------------------------------- |
| `accordion_close` | When a user closes an accordion. |
| `accordion_open` | When a user opens an accordion. |
| `api_playground_call` | When a user calls an API in the API playground. |
| `code_block_copy` | When a user copies code from a code block. |
| `cta_click` | When a user clicks a call to action. |
| `expandable_close` | When a user closes an expandable. |
| `expandable_open` | When a user opens an expandable. |
| `header_nav_item_click` | When a user clicks a header navigation item. |
| `pageview` | When a user views a page. |
| `powered_by_mintlify_click` | When a user clicks the "Powered by Mintlify" link. |
| `scroll_to_bottom` | When a user scrolls to the bottom of a page. |
| `thumb_vote` | When a user votes (thumbs up or down) on a page. |
| `ai_chat_citation_click` | When a user clicks a citation in a chat. |
| `ai_chat_feedback_positive_click` | When a user clicks the positive feedback button in a chat. |
| `ai_chat_feedback_negative_click` | When a user clicks the negative feedback button in a chat. |
| `chat_completed` | When a chat session is completed. |
| `chat_enter` | When a user initiates a chat. |
| `chat_followup` | When a user sends a follow up message. |
| `chat_shared` | When a user shares a chat conversation. |
| `search_close` | When a user closes the search bar. |
| `search_result_click` | When a user clicks a search result. |
# Pirsch
Source: https://mintlify.com/docs/integrations/analytics/pirsch
Add the following to your `docs.json` file to send analytics to Pirsch.
You can get your site ID from Settings > Developer > Identification Code.
```json Analytics options in docs.json
"integrations": {
"pirsch": {
"id": "required"
}
}
```
```json Example
"integrations": {
"pirsch": {
"id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp"
}
}
```
# Plausible
Source: https://mintlify.com/docs/integrations/analytics/plausible
Add your site's domain to `docs.json` to send analytics to Plausible.
Do not include `https://` for the domain or server.
```json Analytics options in docs.json
"integrations": {
"plausible": {
"domain": "required",
"server": "optional"
}
}
```
```json Example
"integrations": {
"plausible": {
"domain": "docs.domain.com"
}
}
```
# PostHog
Source: https://mintlify.com/docs/integrations/analytics/posthog
Add the following to your `docs.json` file to send analytics to PostHog.
You only need to include `apiHost` if you are self-hosting PostHog. We send events to `https://app.posthog.com` by default.
```json Analytics options in docs.json
"integrations": {
"posthog": {
"apiKey": "YOUR_POSTHOG_PROJECT_API_KEY",
"apiHost": "optional"
}
}
```
```json Example
"integrations": {
"posthog": {
"apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW"
}
}
```
Enabling PostHog analytics will disable the analytics on the Mintlify dashboard.
## Session Recordings
You need to add the URL for your docs website to Posthog's "Authorized domains for recordings" before you can receive session recordings. The option to add your URL is in Posthog's project settings.
# Segment
Source: https://mintlify.com/docs/integrations/analytics/segment
Add your Segment write key to your `docs.json` file to send analytics to Segment.
```json Analytics options in docs.json
"integrations": {
"segment": {
"key": "required",
}
}
```
```json Example
"integrations": {
"segment": {
"key": "nqJxiRG15Y6M594P8Sb8ESEciU3VC2"
}
}
```
# Osano
Source: https://mintlify.com/docs/integrations/privacy/osano
Add the following to your `docs.json` file to add the [Osano](https://www.osano.com/) cookie consent manager.
```json Integration options in docs.json
"integrations": {
"osano": "SOURCE"
}
```
```json Example
"integrations": {
"osano": "https://cmp.osano.com/2sUB2dqwqdkks/8dqwd-dwd86£-4a9b/osano.js"
}
```
The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`.
```html Code snippet from Osano
```
# Privacy Integrations
Source: https://mintlify.com/docs/integrations/privacy/overview
Integrate with a data privacy platform
} horizontal />
## Enabling Data Privacy Integrations
You can add data privacy platforms onto your docs. Add the `integrations` field into your `docs.json` file with your respective scripts.
```json
"integrations": {
"osano": "SOURCE"
}
```
If you'd like to request a data privacy platform integration, please let us know in [our community](https://mintlify.com/community).
## Cookie Consent and Disabling Telemetry
If you need to check if a user has already consented to cookies for GDPR compliance, you can specify a local storage key and value under `cookies`:
```json
"integrations": {
"cookies": {
"key": "LOCAL STORAGE KEY",
"value": "LOCAL STORAGE VALUE"
}
}
```
If these values are set, local storage will be checked to see if the user has consented to cookies. If they have not, telemetry will be disabled.
If you'd like to disable telemetry for all users, you can add the following to your `docs.json` file:
```json
"integrations": {
"telemetry": {
"enabled": false
}
}
```
# Speakeasy
Source: https://mintlify.com/docs/integrations/sdks/speakeasy
Automate your SDK usage snippets in the API playground
You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of your Mintlify-powered documentation.
## Speakeasy SDK Repository Changes
In your Speakeasy SDK repos, add the following to the `targets` section of your `.speakeasy/workflow.yaml` file to ensure code samples are automatically produced alongside SDK generations.
```yaml .speakeasy/workflow.yaml
targets:
my-target:
target: typescript
source: my-source
codeSamples:
output: codeSamples.yaml
```
Code samples will be generated in the form of an [OpenAPI overlay file](https://www.speakeasyapi.dev/openapi/overlays) that will be used in the Mintlify docs repository.
## Mintlify Docs Repository Changes
The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, `openapi.yaml`. Mintlify will use this output file when constructing your API reference.
### Interactive CLI Set Up
Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI.
```bash
speakeasy configure sources
speakeasy configure github
```
Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it's often the same specification used to power Mintlify docs.

Add the overlay created by Speakeasy to inject code snippets into your spec.

Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.

Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.
## Manual Set Up
Alternatively, you can manually set up the following files in your Mintlify docs repo.
```yaml .speakeasy/workflow.yaml
workflowVersion: 1.0.0
sources:
docs-source:
inputs:
- location: {{your_api_spec}} # local or remote references supported
overlays:
- location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/codeSamples.yaml
- location: https://raw.githubusercontent.com/{{your_sdk_repo_2}}/codeSamples.yaml
- location: https://raw.githubusercontent.com/{{your_sdk_repo_3}}/codeSamples.yaml
output: openapi.yaml
targets: {}
```
```yaml .speakeasy/workflows/sdk_generation.yaml
name: Generate
permissions:
checks: write
contents: write
pull-requests: write
statuses: write
"on":
workflow_dispatch:
inputs:
force:
description: Force generation of SDKs
type: boolean
default: false
schedule:
- cron: 0 0 * * *
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
with:
force: ${{ github.event.inputs.force }}
mode: pr
speakeasy_version: latest
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
```
Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.
# Stainless
Source: https://mintlify.com/docs/integrations/sdks/stainless
Automate SDK example snippets in your API playground
## Prerequisites
* Have a [Stainless](https://app.stainless.com) account.
## Integrate with Stainless
In your `stainless.yml` config file, add `openapi.code_samples: 'mintlify'`. See the [Stainless documentation](https://app.stainless.com/docs/guides/integrate-docs) for more information.
In your Stainless project:
1. Select the **Release** tab.
2. Select **Setup OpenAPI publishing**.
3. Copy the URL to your publicly accessible OpenAPI spec.
Add your OpenAPI spec URL to your docs.json.>}>
In your `docs.json` file, add the URL from Stainless to the `openapi` field. See [OpenAPI Setup](/api-playground/openapi-setup) for more information.
# Front
Source: https://mintlify.com/docs/integrations/support/front
Add the following to your `docs.json` file to add a [Front Chat](https://front.com) widget.
```json Integration options in docs.json
"integrations": {
"frontchat": "CHAT_ID"
}
```
```json Example
"integrations": {
"frontchat": "1365d046d7c023e9b030ce90d02d093a"
}
```
# Intercom
Source: https://mintlify.com/docs/integrations/support/intercom
Add the following to your `docs.json` file to add an [Intercom](https://www.intercom.com) widget.
```json Integration options in docs.json
"integrations": {
"intercom": {
"appId": "APP_ID"
}
}
```
```json Example
"integrations": {
"intercom": {
"appId": "APP_ID"
}
}
```
# Support Integrations
Source: https://mintlify.com/docs/integrations/support/overview
Integrate with a support widget
} horizontal />
}
horizontal
/>
## Enabling Support Integrations
You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `docs.json` file with your respective app ID.
```json
"integrations": {
"intercom": "APP_ID",
"frontchat": "CHAT_ID"
}
```
If you'd like to request a customer support integration, please let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA).
# Lists and Tables
Source: https://mintlify.com/docs/list-table
Display information in lists and tables
## Lists
### Ordered List
To create an ordered list, add line items with numbers followed by periods
1. First item
2. Second item
3. Third item
4. Fourth item
```mdx
1. First item
2. Second item
3. Third item
4. Fourth item
```
### Unordered List
To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items.
* First item
* Second item
* Third item
* Fourth item
```mdx
- First item
- Second item
- Third item
- Fourth item
```
### Nested List
Add indents on list items to nest them
* First item
* Second item
* Additional item
* Additional item
* Third item
```mdx
- First item
- Second item
- Additional item
- Additional item
- Third item
```
Lists follow the official [markdown syntax](https://www.markdownguide.org/basic-syntax/#lists-1).
## Tables
| Property | Description |
| -------- | ------------------------------------- |
| Name | Full name of user |
| Age | Reported age |
| Joined | Whether the user joined the community |
### Creating a table
The Table component follows the official [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables).
To add a table, use three or more hyphens (`---`) to create each column's header, and use pipes (`|`) to separate each column. For compatibility, you should also add a pipe on either end of the row.
```mdx
| Property | Description |
| -------- | ------------------------------------- |
| Name | Full name of user |
| Age | Reported age |
| Joined | Whether the user joined the community |
```
# Model Context Protocol
Source: https://mintlify.com/docs/mcp
Generate MCP servers from your documentation or OpenAPI specs
## Overview
The Model Context Protocol (MCP) is an open protocol that connects your functions to LLMs and AI applications. With Mintlify's integration, you can automatically generate an MCP server from your existing documentation or OpenAPI specifications, enabling seamless AI-powered interactions with your product.
## Quick Usage Guide
Any public documentation hosted on Mintlify can be extracted as an MCP server using a simple command:
```bash
npx mint-mcp add
```
Examples:
```bash
# Using subdomain
npx mint-mcp add mintlify
# Using domain
npx mint-mcp add mintlify.com
```
### Authentication
When you run the command, you'll need to provide two API keys, `External Admin Key` and `Assistant API Key`.
These can be found in your [Mintlify Dashboard](https://dashboard.mintlify.com/settings/organization/api-keys) under **Settings > API Keys**.
### Select MCP Clients
After authentication, you'll choose which MCP clients to enable for your server:
Once configured, your MCP server is ready to use with the command provided in the terminal.
## Configuring Your MCP Server
Now let's take a look at how to configure your MCP server.
### Default Functionality
All MCP servers include the `search` tool by default, allowing users to query information across your entire documentation.
### Adding API Functions
If you have an OpenAPI specification, you can expose specific endpoints as MCP tools by using the `x-mcp` extension at either the file or endpoint level.
#### File-Level Configuration
Enable MCP for all endpoints in a specification file:
```json
{
"openapi": "3.1.0",
"x-mcp": {
"enabled": true
},
// Other OpenAPI content
}
```
#### Endpoint-Level Configuration
Enable MCP for specific endpoints only:
```json
{
"paths": {
"/api/v1/users": {
"x-mcp": {
"enabled": true
},
// Endpoint configuration
}
}
}
```
### Authentication Handling
If your OpenAPI spec defines authentication using securitySchemes, these authentication methods will be automatically applied to your MCP server.
### Monitoring Your MCP Server
After publishing your changes, you can view all available MCP tools in the **Available Tools** section on the MCP server page in your dashboard.
## Distribution
### User Installation
Your users can install and use your MCP server with:
```bash
npx mint-mcp add
```
This provides them with a ready-to-use MCP server that connects your documented functions to AI applications.
# Navigation
Source: https://mintlify.com/docs/navigation
Structure and customize your documentation's navigation hierarchy
The [navigation](settings#param-navigation) property in [docs.json](settings) defines how users will browse through your documentation. Think of it as the blueprint for your documentation's menu structure.
With proper navigation configuration, you can organize your content into a logical hierarchy that makes it easy for users to find exactly what they're looking for.
Do not use `api` as a title for any navigation element. The `/api` path is reserved in production and will cause pages to return 404 errors if their URLs contain `/api`.
## Pages
Pages are the most fundamental navigation component.
Pages is an array where each entry must be a reference to the path of a [page file](pages).
```json
{
"navigation": {
"pages": [
"overview",
"quickstart",
"advanced/components",
"advanced/integrations"
]
}
}
```
***
## Groups
Use groups to organize your navigation into sections. Groups can be nested within each other, labeled with tags, and styled with icons.
```json
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"icon": "play",
"pages": [
"quickstart",
{
"group": "Editing",
"icon": "pencil",
"pages": [
"installation",
"editor",
{
"group": "Nested group",
"icon": "code",
"pages": [
"navigation",
"code"
]
}
]
}
]
},
{
"group": "Writing Content",
"icon": "notebook-text",
"tag": "NEW",
"pages": ["writing-content/page", "writing-content/text"]
}
]
}
}
```
## Tabs
Tabs help distinguish between different topics or sections of your
documentation.
```json
"navigation": {
"tabs": [
{
"tab": "API References",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"tab": "SDKs",
"pages": [
"sdk/fetch",
"sdk/create",
"sdk/delete",
]
},
{
"tab": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
## Anchors
Anchors are another way to section your content. They show up on top of your side navigation.
The configuration is very similar to tabs.
While not required, we highly recommend that you set an `icon` field as well.
```json
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
},
{
"anchor": "API References",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"anchor": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
Anchors that strictly contain external links can be achieved using the `global` keyword:
```json
"navigation": {
"global": {
"anchors": [
{
"anchor": "Community",
"icon": "house",
"href": "https://slack.com"
},
{
"anchor": "Blog",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
```
## Dropdowns
Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
While not required, we also recommend that you set an icon for each dropdown item.
```json
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"dropdown": "API References",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"dropdown": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
***
## Versions
Versions can be leveraged to partition your navigation into different versions.
```json
{
"navigation": {
"versions": [
{
"version": "1.0.0",
"groups": [
{
"group": "Getting Started",
"pages": ["v1/overview", "v1/quickstart", "v1/development"]
}
]
},
{
"version": "2.0.0",
"groups": [
{
"group": "Getting Started",
"pages": ["v2/overview", "v2/quickstart", "v2/development"]
}
]
}
]
}
}
```
***
## Languages
Languages can be leveraged to partition your navigation into different languages.
You can automate [translations](/translations) of your documentation into any supported language.
We currently support the following languages:
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
```json
{
"navigation": {
"languages": [
{
"language": "en",
"groups": [
{
"group": "Getting Started",
"pages": ["en/overview", "en/quickstart", "en/development"]
}
]
},
{
"language": "es",
"groups": [
{
"group": "Getting Started",
"pages": ["es/overview", "es/quickstart", "es/development"]
}
]
}
]
}
}
```
***
## Nesting
It's important to note that you can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.
This way, you can create a very complex navigation structure that is easy to manage.
```json Anchors
{
"navigation": {
"anchors": [
{
"anchor": "Anchor 1",
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2"
"just-a-file"
]
}
]
}
{
"anchor": "Anchor 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
```json Tabs
{
"navigation": {
"tabs": [
{
"tab": "Tab 1",
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2"
"just-a-file"
]
}
]
}
{
"tab": "Tab 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
```json Tabs with external anchors
{
"navigation": {
"tabs": [
{
"tab": "Tab 1",
"global": {
"anchors": [
{
"anchor": "Anchor 1",
"href": "https://mintlify.com/docs"
}
]
},
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2"
"just-a-file"
]
}
]
}
{
"tab": "Tab 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
# Pages
Source: https://mintlify.com/docs/pages
Pages are the building blocks of your documentation
## Basics
Each page is an MDX file that should begin with `---` at the start and end. This is used to define the page's metadata, such as the title and description.
For example, you can define the title for this page as follows.
```mdx
---
title: "Your title goes here"
---
```
## Descriptions
You can add a description that shows the summary of the page under the title with the `description` metadata.
```mdx
---
description: "Your description goes here"
---
```
## Sidebar Title
If you want to show a different title in the navigation, you can set the `sidebarTitle` metadata. This is useful if your title is long and you want something shorter in the navigation links.
```mdx
---
title: "Your very long page title you want to shorten"
sidebarTitle: "Short title"
---
```
## Icons
Add an icon next to your page's sidebar title by including the `icon` field in your page's frontmatter.
```mdx
---
title: "Code Block"
icon: "code"
---
```
You can set icons from a URL, [Font Awesome](https://fontawesome.com/icons), or [Lucide](https://lucide.dev/icons). Choose your preferred icon library (Font Awesome or Lucide) with the [icon library setting](settings#param-icons).
For Font Awesome icons, you can optionally set the icon type. If not set, the icon type will be regular.
```mdx
---
iconType: "solid"
---
```
## Tag
Add tags to label specific pages. Tags display in the sidebar next to page titles.
```mdx
---
tag: "NEW"
---
```
## API Pages
API pages let you build interactive API playgrounds. To create an API page, you
must set an `api` or `openapi` property in the page metadata.
Learn more about API pages by visiting the [API page guides](/api-playground/overview).
```mdx
---
openapi: "GET /endpoint"
---
```
## Page Mode
The Page Mode setting allows you to customize the appearance of your page. You can choose from
different modes to adjust the layout according to your needs. If no mode is specified, the page
will use the default settings.
### Default
If no specific mode is given, the page will default to standard settings. This means the page
will display the default table of contents and other standard elements.
```mdx
---
title: "Default page title"
---
```
### Wide Mode
In Wide Mode, you can hide the table of contents (ToC) on the right side of the page. This is
particularly useful if your page doesn’t have any headings or if you prefer to utilize the
extra horizontal space for more content.
```mdx
---
mode: "wide"
---
```
### Custom Mode
Custom Mode provides a minimalist layout by removing all elements except for the top bar.
This mode offers a blank canvas, which is ideal for creating a "landing page" or any page where
you want a clean, distraction-free environment.
```mdx
---
mode: "custom"
---
```
### Center Mode
Center Mode removes the sidebar and the table of contents, and centers the page content. This mode is great for changelogs
or any page where you want to focus on the content.
```mdx
---
mode: "center"
---
```
## External Links
If you want the sidebar to open an external URL, you can set the `url` metadata
in any page.
```mdx
---
title: "Page that goes to external link"
url: "https://www.npmjs.com/package/mint"
---
```
## Search Engine Optimization
You can set meta tags like the image set when shared on social media by passing
them into your page's metadata.
Note that meta tags with colons need to be wrapped in quotes.
```mdx
---
"twitter:image": "/images/your-photo.jpg"
---
```
See [SEO](/settings/seo) to learn more about SEO metadata.
## Internal Search Optimization
You can also enhance a specific page's discoverability in the built-in search by
providing `keywords` in your metadata. These keywords won't appear as part of the page
content or in search results, but users that search for them will be shown the page as a result.
```mdx
---
keywords: ['search', 'indexing']
---
```
# Quickstart
Source: https://mintlify.com/docs/quickstart
Deploy your documentation in minutes
This quickstart guide shows you how to set up and deploy your documentation site in minutes.
After you complete this guide, you will have a live documentation site ready to customize and expand.
**Prerequisites**: Before you begin, [create an account](https://mintlify.com/start) and complete onboarding.
## Getting Started
After you complete the onboarding process, your documentation site will automatically deploy to a unique URL with this format:
```
https://.mintlify.app
```
Find your URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/).
This URL becomes available immediately and updates when you make changes to your documentation. Use this URL for testing and sharing with your team during development.
### Install the GitHub App
Mintlify provides a GitHub App that automates deployment when you push changes to your repository.
Install the GitHub App by following the instructions from the onboarding checklist or from your dashboard.
1. Navigate to **Settings** in your Mintlify dashboard.
2. Select **GitHub App** from the sidebar.
3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page.
4. Select the organization or user account where you want to install the app. Then select the repositories that you want to connect.
Update the GitHub App permissions if you move your documentation to a different repository.
### Authorize your GitHub Account
1. Navigate to **Settings** in your Mintlify dashboard.
2. Select **My Profile** from the sidebar.
3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page.
An admin for your GitHub organization may need to authorize your account depending on your organization settings.
## Editing Workflows
Mintlify offers two workflows for creating and maintaining your documentation.
For users who prefer working with existing tools in their local environment. Click to jump to this section.
For users who prefer a visual interface in their web browser. Click to jump to this section.
## Code-Based Workflow
The code-based workflow integrates with your existing development environment and Git repositories. This workflow is best for technical teams who want to manage documentation alongside code.
### Install the CLI
To work locally with your documentation, install the Command Line Interface (CLI), called [mint](https://www.npmjs.com/package/mint), by running this command in your terminal:
```bash npm
npm install -g mint
```
```bash yarn
yarn global add mint
```
```bash pnpm
pnpm add -g mint
```
You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide.
### Edit the Documentation
After you set up your environment, you can start editing your documentation files. For example, update the title of the introduction page:
Open your repository created during onboarding, find the `introduction.mdx` file, and find the top of the file:
```mdx introduction.mdx
---
title: "Introduction"
description: "This is the introduction to the documentation"
---
```
Update the `title` field to `"Hello World"`.
```mdx introduction.mdx {2}
---
title: "Hello World"
description: "This is the introduction to the documentation"
---
```
### Preview the Changes
To preview the changes locally, run this command:
```bash
mint dev
```
Your preview will be available at `localhost:3000`.
### Push the Changes
When you are ready to publish your changes, push the changes to your repository.
Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com).
After the deployment is complete, your latest update will be available at `.mintlify.app`.
Optionally, skip the web editor workflow and jump to adding a custom domain.
## Web Editor Workflow
The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. This workflow is best for people who want to work in their web browser without additional local development tools.
### Access the Web Editor
1. Log in to your [Mintlify Dashboard](https://dashboard.mintlify.com).
2. Select **Editor** on the left sidebar.
If you have not installed the GitHub App, you will be prompted to install the app when you open the web editor.
### Edit the Documentation
In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page:
Find and click on `introduction.mdx` in the file explorer.
Then, in the visual editor, update the title field to "Hello World".
The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools.
### Publish Your Changes
When you are satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site.
Use branches to preview and review changes through pull requests before deploying to your live site.
For more details about using the web editor, including using branches and pull request to collaborate and preview changes, see our [Web Editor documentation](/editor).
## Adding a Custom Domain
While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation.
To add a custom domain, go to `Settings` > `Custom Domain` from the dashboard.
Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS (Domain Name System) settings with your domain provider.
| Record Type | Name | Value | TTL |
| ----------- | ------------------- | ------------------ | ---- |
| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 |
DNS changes can take up to 48 hours to propagate, though changes often complete much sooner.
## Next Steps
Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation:
Learn how to customize colors, fonts, and the overall appearance of your documentation site.
Structure your documentation with intuitive navigation to help users find what they need.
Enhance your documentation with interactive components like accordions, tabs, and code samples.
Create interactive API references with OpenAPI and AsyncAPI specifications.
## Troubleshooting
If you encounter issues during the setup process, check these common troubleshooting solutions:
Make sure you have Node.js v19+ installed and that you run the `mint dev` command from the directory containing your `docs.json` file.
Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors.
Verify that your DNS records are set up correctly and allow sufficient time for DNS propagation (up to 48 hours). You can use tools like [DNSChecker](https://dnschecker.org) to verify your CNAME record.
Need more help? [Contact our Support Team](https://mintlify.com/docs/support).
# React
Source: https://mintlify.com/docs/react-components
Build interactive and reusable elements with React components
export const ColorGenerator = () => {
const [hue, setHue] = useState(165);
const [saturation, setSaturation] = useState(84);
const [lightness, setLightness] = useState(31);
const [colors, setColors] = useState([]);
useEffect(() => {
const newColors = [];
for (let i = 0; i < 5; i++) {
const l = Math.max(10, Math.min(90, lightness - 20 + i * 10));
newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`);
}
setColors(newColors);
}, [hue, saturation, lightness]);
const copyToClipboard = color => {
navigator.clipboard.writeText(color).then(() => {
console.log(`Copied ${color} to clipboard!`);
}).catch(err => {
console.error("Failed to copy: ", err);
});
};
return
{colors.map((color, idx) =>
copyToClipboard(color)} />)}
Base color: hsl({hue}, {saturation}%, {lightness}%)
;
};
[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation.
You can use React directly in your MDX files without any additional setup.
## Using React Components
You can build components directly in your MDX files using [React hooks](https://react.dev/reference/react/hooks).
### Basic Example
Here's a basic example of a counter component:
```mdx
export const Counter = () => {
const [count, setCount] = useState(0);
return (
Current count: {count}
);
}
```
The `Counter` component can then be used in your MDX files like this:
```mdx
```
And the component will be rendered as a React component in the MDX file.
## Importing Components
Just like in regular React, you can import components from other files.
```mdx
import { ColorGenerator } from "/snippets/color-generator.mdx"
```
But unlike regular React, you can't import components from every MDX file. Re-usable components can only be referenced from MDX files within the `snippets` folder.
After importing the component, you can use it in your MDX files like this:
```mdx
```
Learn more about [reusable snippets](/reusable-snippets).
### Complex Example
You can also build much more complex components. Here's an example of a color generator component that uses multiple React hooks:
```mdx /snippets/color-generator.mdx [expandable]
export const ColorGenerator = () => {
const [hue, setHue] = useState(180)
const [saturation, setSaturation] = useState(50)
const [lightness, setLightness] = useState(50)
const [colors, setColors] = useState([])
useEffect(() => {
const newColors = []
for (let i = 0; i < 5; i++) {
const l = Math.max(10, Math.min(90, lightness - 20 + i * 10))
newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`)
}
setColors(newColors)
}, [hue, saturation, lightness])
const copyToClipboard = (color) => {
navigator.clipboard
.writeText(color)
.then(() => {
console.log(`Copied ${color} to clipboard!`)
})
.catch((err) => {
console.error("Failed to copy: ", err)
})
}
return (
{colors.map((color, idx) => (
copyToClipboard(color)}
/>
))}
Base color: hsl({hue}, {saturation}%, {lightness}%)
)
}
```
The above component can then be used in your MDX files like this:
```mdx
```
And the component will be rendered as a React component in the MDX file.
## Considerations
React hook components render on the client-side, which has several implications:
* **SEO**: Search engines might not fully index dynamic content
* **Initial Load**: Visitors may experience a flash of loading content before components render
* **Accessibility**: Ensure dynamic content changes are announced to screen readers
* **Optimize Dependency Arrays**: Include only necessary dependencies in your `useEffect` dependency arrays
* **Memoize Complex Calculations**: Use `useMemo` or `useCallback` for expensive operations
* **Reduce Re-renders**: Break large components into smaller ones to prevent cascading re-renders
* **Lazy Loading**: Consider lazy loading complex components to improve initial page load time
# Reusable Snippets
Source: https://mintlify.com/docs/reusable-snippets
Reusable, custom snippets to keep content in sync
One of the core principles of software development is DRY (Don't Repeat
Yourself), which applies to documentation as
well. If you find yourself repeating the same content in multiple places, you
should create a custom snippet to keep your content in sync.
## Creating a custom snippet
**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work.
Any page in the `snippets` directory will be treated as a snippet and will not
be rendered into a standalone page. If you want to create a standalone page
from the snippet, import the snippet into another file and call it as a
component.
### Default export
1. Add content to your snippet file that you want to re-use. Optionally, you can add variables that can be filled in via props
when you import the snippet. In this example, our variable is word.
```typescript snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages.
```
2. Import the snippet into your destination file.
```typescript destination-file.mdx
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
### Exporting with variables
1. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word.
```typescript snippets/my-snippet.mdx
My keyword of the day is {word}.
```
2. Import the snippet into your destination file with the variable. The property will fill in based on your specification.
```typescript destination-file.mdx
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
### Reusable variables
1. Export a variable from your snippet file:
```typescript snippets/path/to/custom-variables.mdx
export const myName = 'my name';
export const myObject = { fruit: 'strawberries' };
```
2. Import the snippet from your destination file and use the variable:
```typescript destination-file.mdx
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.
```
# Settings
Source: https://mintlify.com/docs/settings
Configure the global settings for your documentation
Every documentation site requires a **docs.json** file.
This file contains the global configuration settings and controls everything from styling and navigation to integrations.
## Reference
This section contains the full reference for the docs.json file.
### Customization
One of the following: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`.
The layout theme of the project. Check out the [Themes](themes) page for more information.
The name of the project, organization, or product
The colors to use in your documentation. At the very least, you must define the primary color. For example:
```json
{
"colors": {
"primary": "#ff0000"
}
}
```
The primary color of the theme
Must be a hex code beginning with `#`
The light color of the theme. Used for dark mode
Must be a hex code beginning with `#`
The dark color of the theme. Used for light mode
Must be a hex code beginning with `#`
Optional description used for SEO and LLM indexing
The logo (for both light and dark mode)
Path pointing to the light logo file to use in dark mode, including the file extension. Example: `/logo.png`
Path pointing to the dark logo file to use in light mode, including the file extension. Example: `/logo-dark.png`
The URL to redirect to when clicking the logo. If not provided, the logo will link to the homepage. Example: `https://example.com`
The path to your favicon file in the docs folder, including the file extension. The file will automatically be resized to appropriate favicon sizes.
Can be a single file or a pair for light and dark mode. Example: `/favicon.png`
Path pointing to the light favicon file to use in dark mode, including the file extension. Example: `/favicon.png`
Path pointing to the dark favicon file to use in light mode, including the file extension. Example: `/favicon-dark.png`
Styling configurations
The eyebrows style of the content. Defaults to `section`.
The codeblock theme. Defaults to `system`.
Icon library settings
The icon library to be used. Defaults to `fontawesome`.
The font family, such as "Open Sans", "Playfair Display"
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
The font format, can be one of woff, woff2
The font family, such as "Open Sans", "Playfair Display"
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
The font format, can be one of woff, woff2
The font family, such as "Open Sans", "Playfair Display"
The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.
The font source, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2)
The font format, can be one of woff, woff2
Light / dark mode toggle settings
The default light/dark mode. Defaults to `system`
Whether to hide the light / dark mode toggle. Defaults to `true`.
Background color and decoration settings
The background decoration of the theme
The colors of the background
The color in hex format to use in light mode
Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})\$
The color in hex format to use in dark mode
Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})\$
### Structure
Navbar content and settings
The links in the navbar
The display text for a link.
A valid path or external link.
The icon displayed for a link. Can be a URL, Font Awesome icon, or Lucide icon.
The label for the primary button. This only applies when `type` is set to `button`.
A valid path or external link. If `type` is set to `github`, this will be the URL to the repository.
The navigation structure of the content
Add external links that will appear on all sections and pages irregardless of navigation nesting
The name of the language in the ISO 639-1 format
Whether this language is the default language
Whether the current option is default hidden
A valid path or external link
The name of the version
Minimum length: 1
Whether this version is the default version
Whether the current option is default hidden
An external link
The name of the tab
Minimum length: 1
The icon to be displayed in the section
Whether the current option is default hidden
An external link
The name of the anchor
Minimum length: 1
The icon to be displayed in the section
The color in hex format to use in light mode
Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})\$
The color in hex format to use in dark mode
Must match pattern: ^#(\[a-fA-F0-9]{6}|\[a-fA-F0-9]{3})\$
Whether the current option is default hidden
A valid path or external link
The name of the dropdown
Minimum length: 1
The icon to be displayed in the section
Whether the current option is default hidden
An external link
Organizing by [languages](navigation#localization)
Organizing by [versions](navigation#versions)
Organizing by [tabs](navigation#divisions#tabs)
Organizing by [anchors](navigation#divisions#anchors)
Organizing by [dropdowns](navigation#divisions#dropdowns)
Organizing by [groups](navigation#pages#pages)
An array of [page paths or groups](navigation#pages#groups)
Footer configurations
An object in which each key is the name of a social media platform, and each value is the url to your profile. For example:
```json
{
"x": "https://x.com/mintlify"
}
```
Valid property names: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast`
The links to be displayed in the footer
The header title of the column
Minimum length: 1
The links to be displayed in the column
The label of the link
Minimum length: 1
The url of the link
Banner configurations
The content of the banner. This can be a string of text or a markdown string. For example:
```json
{
"content": "🚀 Banner is live! [Learn more](mintlify.com)"
}
```
Whether the banner is dismissible. Defaults to `false`.
The options to be displayed in the contextual menu. The first option is the default option.
* `copy`: Copy the current page as markdown to the clipboard
* `view`: View the current page as markdown in a new tab
* `chatgpt`: Feed the current page to ChatGPT
* `claude`: Feed the current page to Claude
The contextual menu is only available on preview & production deployments.
### API Configurations
API reference configuration and playground settings
A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s)
Minimum length: 1
no starting slash in the directory
A string or an array of strings of absolute or relative urls pointing to the AsyncAPI file(s)
Minimum length: 1
Configurations for the API parameters
The view mode of expandable API parameters. Defaults to `closed`.
Configurations for the API playground
The display mode of the API playground. 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
Whether to show optional parameters in api examples, defaults to `all`
Configurations for API pages generated from MDX files
Authentication configuration for the API
Authentication method for the API
Authentication name for the API
### SEO & Search
SEO indexing configurations
Meta tags added to every page. Must be a valid key-value pair. Possible options [here](https://mintlify.com/docs/settings/seo#supported-meta-tags)
Specify which pages to be indexed by search engines. Setting `navigable` indexes pages that are set in navigation, `all` indexes all pages. Defaults to `navigable`.
Search display settings
The prompt to be displayed in the search bar placeholder
### Integrations
Configurations for official integrations
Minimum length: 6
Must match pattern: ^G
Must match pattern: ^G
Minimum length: 6
Minimum length: 2
Must match pattern: ^phc\_
### Errors
Whether to redirect to the home page, if the page is not found
## Validation
It is advised to include the following schema reference at the top of your docs.json file to ensure proper validation while editing:
```json
{
"$schema": "https://mintlify.com/docs.json"
/*...*/
}
```
# Redirects and Broken Links
Source: https://mintlify.com/docs/settings/broken-links
Tools to help prevent invalid links
When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title.
## Broken Links
Catch broken links with our CLI. Simply [install the CLI](/installation) and run the command:
```bash
mint broken-links
```
The CLI will identify any relative links in your docs that don't exist.
## Redirects
Set up 301 redirects by adding the `redirects` field into your `docs.json` file.
```json
"redirects": [
{
"source": "/source/path",
"destination": "/destination/path"
}
]
```
This will permanently redirect `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page.
To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`.
```json
"redirects": [
{
"source": "/beta/:slug*",
"destination": "/v2/:slug*"
}
]
```
# CI Checks
Source: https://mintlify.com/docs/settings/ci
Add broken links, linting, and grammar checks to the updating process
This feature is only available for customers on [paid plans](https://mintlify.com/pricing?ref=docs-ci) and for GitHub. Support for other platforms is coming soon. Please{" "}
contact sales for more information.
Use CI checks to lint your docs for errors, and give you warnings before you deploy.
## Installation
To begin, you will need to have followed the steps on the [GitHub](/settings/github) page.
For GitHub Apps, you can choose to only give permissions to a single repository.
We highly recommend you do so as we only need access to the repository where
your docs are hosted.
## Configuration
You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run.
When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.
A `Blocking` level check will provide a failure status if not passed, or changes are suggested.
A `Warning` level check will never provide a failure status, even if there is an error or suggestions.
## When Do They Run?
CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch.
## Available CI Checks
### Broken Links
Similarly to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we will automatically check your docs for broken links.
To see the results of this check, you can visit GitHub's check results page for a specific commit.
### Vale
[Vale](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX.
Mintlify supports automatically running Vale in a CI check, and displaying the results as a check status.
#### Configuration
If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file.
We will also automatically use any configuration files in your specified `stylesPath`.
Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that will automatically be used if one is not provided.
Please note that for security reasons, we are unable to support any absolute `stylesPath`, or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository.
#### Packages
Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors.
Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale configuration.
For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they will automatically be downloaded and used in your Vale configuration.
Please note that for security reasons, we are unable to support automatically downloading packages that are not from the [Vale package registry](https://vale.sh/explorer).
#### Vale with MDX
Vale does not natively support MDX, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it.
If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file:
```ini
[formats]
mdx = md
[*.mdx]
CommentDelimiters = {/*, */}
TokenIgnores = (?sm)((?:import|export) .+?$), \
(?)(?!`), \
(<[A-Z]\w+>.+?<\/[A-Z]\w+>)
BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
(?sm)^({.+.*})
```
To use Vale's in-document comments, use MDX-style comments `{/* ... */}`.
If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale will automatically interpret these comments while linting.
This means you can easily use Vale's in-built features, like skipping lines or sections.
```mdx
{/* vale off */}
This text will be ignored by Vale
{/* vale on */}
```
If you choose not to use `CommentDelimiters`, but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example:
```mdx
{/* */}
This text will be ignored by Vale
{/* */}
```
Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.
# Custom Domain
Source: https://mintlify.com/docs/settings/custom-domain
Host your documentation at your website's custom domain
To set up your documentation on a custom domain, you'll need to set your desired custom domain in your Mintlify settings and configure your DNS settings on your domain provider.
Looking to set up a custom subdirectory like mintlify.com/docs? Find
instructions [here](/advanced/subpath/cloudflare).
## Dashboard Settings
1. Head over to the [dashboard](https://dashboard.mintlify.com)
2. Click on "Settings".
3. Click on "Custom Domain".
4. Enter your desired custom domain. For example, `docs.mintlify.com`.
## Verification with Vercel
If Vercel happens to be your domain provider, you will have to add a verification `TXT` record. This information will show on your dashboard after submitting your custom domain, as well as be emailed to you.
## Configuring your DNS
1. Proceed to your domain's DNS settings on your domain provider's website.
2. Create a new DNS entry, inputting the following values:
```bash
CNAME | docs | cname.vercel-dns.com.
```
If you are using Cloudflare for your DNS provider, you'll need to have the “full strict” security option enabled for the https setting.
Please [contact support](mailto:sales@mintlify.com) if you don't see the custom domain set up after the above configuration.
# Custom Scripts
Source: https://mintlify.com/docs/settings/custom-scripts
Fully customize your documentation with custom CSS and JS
Add custom CSS and JavaScript to your documentation to fully customize the look and feel.
## Custom CSS
Add CSS files to your repository and their defined class names will be applied and available in all of your `MDX` files.
### Adding `style.css`
For example, you can add the following `style.css` file to customize the styling of the navbar and footer.
```css
#navbar {
background: "#fffff2";
padding: 1rem;
}
footer {
margin-top: 2rem;
}
```
### Using identifiers and selectors
Mintlify has a set of common identifiers and selectors to help you tag important elements of the UI.
Use inspect element to find references to elements you're looking to customize.
* APIPlaygroundInput: `api-playground-input`
* AssistantEntry: `assistant-entry`
* AssistantEntryMobile: `assistant-entry-mobile`
* Banner: `banner`
* ChangelogFilters: `changelog-filters`
* ChangelogFiltersContent: `changelog-filters-content`
* ChatAssistantSheet: `chat-assistant-sheet`
* ChatAssistantTextArea: `chat-assistant-textarea`
* ContentArea: `content-area`
* ContentContainer: `content-container`
* ContentSideLayout: `content-side-layout`
* Footer: `footer`
* Header: `header`
* NavBarTransition: `navbar-transition`
* NavigationItems: `navigation-items`
* Navbar: `navbar`
* PageContextMenu: `page-context-menu`
* PageContextMenuButton: `page-context-menu-button`
* PageTitle: `page-title`
* Pagination: `pagination`
* Panel: `panel`
* RequestExample: `request-example`
* ResponseExample: `response-example`
* SearchBarEntry: `search-bar-entry`
* SearchBarEntryMobile: `search-bar-entry-mobile`
* SearchInput: `search-input`
* Sidebar: `sidebar`
* SidebarContent: `sidebar-content`
* TableOfContents: `table-of-contents`
* TableOfContentsContent: `table-of-contents-content`
* TableOfContentsLayout: `table-of-contents-layout`
* TopbarCtaButton: `topbar-cta-button`
* Accordion: `accordion`
* AccordionGroup: `accordion-group`
* AlmondLayout: `almond-layout`
* AlmondNavBottomSection: `almond-nav-bottom-section`
* AlmondNavBottomSectionDivider: `almond-nav-bottom-section-divider`
* Anchor: `nav-anchor`
* Anchors: `nav-anchors`
* APISection: `api-section`
* APISectionHeading: `api-section-heading`
* APISectionHeadingSubtitle: `api-section-heading-subtitle`
* APISectionHeadingTitle: `api-section-heading-title`
* Callout: `callout`
* Card: `card`
* CardGroup: `card-group`
* ChatAssistantSheet: `chat-assistant-sheet`
* ChatAssistantSheetHeader: `chat-assistant-sheet-header`
* ChatAssistantSheetContent: `chat-assistant-sheet-content`
* ChatAssistantInput: `chat-assistant-input`
* ChatAssistantSendButton: `chat-assistant-send-button`
* CodeBlock: `code-block`
* CodeGroup: `code-group`
* Content: `mdx-content`
* DropdownTrigger: `nav-dropdown-trigger`
* DropdownContent: `nav-dropdown-content`
* DropdownItem: `nav-dropdown-item`
* DropdownItemTextContainer: `nav-dropdown-item-text-container`
* DropdownItemTitle: `nav-dropdown-item-title`
* DropdownItemDescription: `nav-dropdown-item-description`
* DropdownItemIcon: `nav-dropdown-item-icon`
* Expandable: `expandable`
* Eyebrow: `eyebrow`
* FeedbackToolbar: `feedback-toolbar`
* Field: `field`
* Frame: `frame`
* Icon: `icon`
* Link: `link`
* LoginLink: `login-link`
* Logo: `nav-logo`
* Mermaid: `mermaid`
* MethodNavPill: `method-nav-pill`
* MethodPill: `method-pill`
* NavBarLink: `navbar-link`
* NavTagPill: `nav-tag-pill`
* NavTagPillText: `nav-tag-pill-text`
* OptionDropdown: `option-dropdown`
* PaginationNext: `pagination-next`
* PaginationPrev: `pagination-prev`
* PaginationTitle: `pagination-title`
* Panel: `panel`
* SidebarGroup: `sidebar-group`
* SidebarGroupIcon: `sidebar-group-icon`
* SidebarGroupHeader: `sidebar-group-header`
* SidebarTitle: `sidebar-title`
* Step: `step`
* Steps: `steps`
* Tab: `tab`
* Tabs: `tabs`
* TabsBar: `nav-tabs`
* TabsBarItem: `nav-tabs-item`
* TableOfContents: `toc`
* TableOfContentsItem: `toc-item`
* Tooltip: `tooltip`
* TopbarRightContainer: `topbar-right-container`
* TryitButton: `tryit-button`
* Update: `update`
References and the styling of common elements are subject to change as the platform evolves. Please use custom styling with caution.
## Custom JavaScript
Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `