# Editor Permissions
Source: https://mintlify.mintlify.review/advanced/dashboard/permissions
Allow more members of your team to update your docs
The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify.
If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check.
In the details of the git check warning, you'll find the link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.
Learn more about our pricing [here](https://mintlify.com/pricing).
# Single Sign-On (SSO)
Source: https://mintlify.mintlify.review/advanced/dashboard/sso
Customize how your team can login to your admin dashboard
Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us!
SSO functionality is available on our Enterprise plan. [Contact
us](https://mintlify.com/enterprise) to learn more!
## 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!
# Create a chat topic
Source: https://mintlify.mintlify.review/advanced/rest-api/chat/create-topic
POST /chat/topic
Creates a topic to manage message history for a given AI chat conversation.
# Generate a message completion
Source: https://mintlify.mintlify.review/advanced/rest-api/chat/generate-message
POST /chat/message
Generate a completion in response to a user query
# Overview
Source: https://mintlify.mintlify.review/advanced/rest-api/overview
## Trigger Updates
You can leverage the REST API to programmatically trigger an update when desired.
While the primary use-case will be to trigger updates, we will be adding more and more
functionality to the API overtime. Let us know what else you want to see in
[our community](https://mintlify.com/community)!
## 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](/advanced/rest-api/update/trigger).
## Chat API key
The Chat API allows you to embed the AI chat 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 Chat 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 chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
# Get the status of an update
Source: https://mintlify.mintlify.review/advanced/rest-api/update/status
GET /project/update-status/{statusId}
# Trigger an update
Source: https://mintlify.mintlify.review/advanced/rest-api/update/trigger
POST /project/update/{projectId}
Trigger an update after updating your OpenAPI document by calling this endpoint in a CI check.
# Cloudflare
Source: https://mintlify.mintlify.review/advanced/subpath/cloudflare
Host documentation at a /docs subpath using Cloudflare Workers
## Create Cloudflare Worker
Navigate to the `Workers & Pages > Create application > Create worker`. You
should be presented with the following screen where you can create a new
Cloudlfare worker.
Keep in mind: If your DNS provider is Cloudflare you should not use proxying for the CNAME record
### Add custom domain
Once the worker is created, click `Configure worker`. Navigate to the worker
`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain
into the list - we recommend you add both the version with and without `www.`
prepended to the domain.
If you have trouble setting up a custom subdirectory,
[contact our support team](mailto:sales@mintlify.com) and we'll walk you through
upgrading your hosting with us.
### Edit Worker Script
Click on `Edit Code` and add the following script into the worker's code.
Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and
`CUSTOM_URL` 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);
}
}
```
Click on `Deploy` and wait for the changes to propagate (it can take up to a few
hours).
# AWS Route 53 and Cloudfront
Source: https://mintlify.mintlify.review/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](mailto:support@mintlify.com) 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.mintlify.review/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)
# Authentication
Source: https://mintlify.mintlify.review/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 on every page or you can set it on a per-page basis.
The page's authentication method will override docs.json if both are set.
### Bearer Token
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
```
```md Page Metadata
---
title: "Your page title"
authMethod: "bearer"
---
```
### Basic Authentication
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}
```
```md Page Metadata
---
title: "Your page title"
authMethod: "basic"
---
```
### API Key
```json docs.json
"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
```md 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.
```md Page Metadata
---
title: "Your page title"
authMethod: "none"
---
```
# MDX Setup
Source: https://mintlify.mintlify.review/api-playground/mdx/configuration
Generate docs pages for your API endpoints using MDX
Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, 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 would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
```json
"api": {
"playground": {
"display": "none"
}
}
```
Find a full list of API configurations [here](/settings/global#param-api).
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
```md
---
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 `server` configured in [docs.json](/settings/global), you can use relative paths like `/v1/endpoint`.
You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file:
```md
---
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 [here](/settings/navigation).
# Advanced Features
Source: https://mintlify.mintlify.review/api-playground/openapi/advanced-features
Support for advanced OpenAPI features
OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them with Mintlify.
## `oneOf`, `anyOf`, `allOf`
For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the [Swagger documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially:
* `oneOf` functions like an "exclusive-or" operator
* `anyOf` functions like an "or" operator
* `allOf` functions like an "and" operator
The `oneOf` and `anyOf` keywords are treated the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user.The `not` keyword is not currently supported.
### Combining schemas with `allOf`
Mintlify performs some preprocessing on your OpenAPI document to display these 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`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. 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
## `x-codeSamples`
If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within 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's an example of some 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 });
```
# OpenAPI Setup
Source: https://mintlify.mintlify.review/api-playground/openapi/setup
Reference OpenAPI endpoints in your docs pages
## Add an OpenAPI specification file
To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
document in either JSON or YAML format that follows the
[OpenAPI specification](https://swagger.io/specification/). Your document must
follow OpenAPI specification 3.0+.
To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command: `mintlify openapi-check `
## Auto-populate API pages
The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab.
**Example with Tabs:**
```json {5}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
**Example with Groups:**
```json {8-11}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
}
]
}
]
}
```
When using this option, 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.
There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.
## 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'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases).
### Manually specify files
You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
By using the OpenAPI reference, the name, description, parameters, responses,
and the API playground will be automatically generated from the OpenAPI document.
If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have
only one OpenAPI file - it will automatically detect your OpenAPI file.
```md Example
---
title: "Get users"
openapi: "/path/to/openapi-1.json GET /users"
---
```
```md Format
---
title: "title of the page"
openapi: openapi-file-path method path
---
```
The method and path must match the method and path specified in the OpenAPI
document exactly. If the endpoint doesn't exist in the OpenAPI file,
the page will be empty.
### Autogenerate files
For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.
Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping)
autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the
OpenAPI document in your codebase.
```bash
npx @mintlify/scraping@latest openapi-file
```
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.
```bash
npx @mintlify/scraping@latest openapi-file -o api-reference
```
Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
The scraper will output an array of
[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
files. You can either append these entries to your existing Navigation, or
reorder and add the files to your navigation manually.
If your OpenAPI document is invalid, the files will not autogenerate.
## Create MDX files for OpenAPI schemas
Mintlify also allows you to create individual pages for any OpenAPI schema
defined in an OpenAPI document's `components.schemas` field:
```md Example
---
openapi-schema: OrderItem
---
```
```md Format
---
openapi-schema: "schema-key"
---
```
# Writing OpenAPI
Source: https://mintlify.mintlify.review/api-playground/openapi/writing-openapi
Use OpenAPI features to enhance your documentation
## Describing your API
There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites:
* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) for familiarizing yourself with the OpenAPI syntax
* [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for all the details about the newest OpenAPI specification
* [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) for debugging your OpenAPI document
* [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action
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, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0).
## Specifying the URL for your API
In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/).
The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request.
If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation.
## Specifying authentication
Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic.
The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document.
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.
# Playground
Source: https://mintlify.mintlify.review/api-playground/overview
GET /plants/{id}
Enable users to interact with your API
The API playground is an interactive environment to make requests and preview an API endpoint.
Autogenerating API pages with OpenAPI will automatically generate API
playground. Read more about using OpenAPI [here](/api-playground/openapi).
# Troubleshooting
Source: https://mintlify.mintlify.review/api-playground/troubleshooting
Common issues with API References
API pages are complicated. As a result, there are a lot of things that can go wrong.
Here's a list of common issues we've seen customers run into:
In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
or your OpenAPI document is invalid.
Running `mintlify dev` locally should reveal some of these issues.
To verify your OpenAPI document will pass validation:
1. Visit [this validator](https://apitools.dev/swagger-parser/online/)
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:
```md 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:
```md 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.disableProxy`
setting in the `docs.json`, as described [here](/settings/global#api-configurations). This will
likely require you to configure CORS on your server, as these requests will now come directly
from your users' browsers.
# Product Updates
Source: https://mintlify.mintlify.review/changelog/overview
New updates and improvements
## 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
```
npm i mintlify@latest -g
```
2. In your docs repository, run
```
mintlify upgrade
```
3. 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 to modify the look & feel of your docs. Configure via your [docs.json file](/settings/global).
Now available:
* Maple
* Palm
## 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](/web-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](/content/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();
```
````md
```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](/content/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/global#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 searchbar 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](/page#custom-mode).
## Mintlify MDX for VSCode
Call snippets of our pre-built components an dcallouts 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 Blocks
Source: https://mintlify.mintlify.review/code
Display inline code and code blocks
## Basic
### Inline Code
To denote a `word` or `phrase` as code, enclose it in backticks (\`).
```
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
### Code Block
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````md
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
Visit the [Code Block page](/content/components/code) for more detailed docs.
# Accordion Groups
Source: https://mintlify.mintlify.review/content/components/accordion-groups
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](/content/components/accordions) docs for all the supported props.
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
````jsx 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](/content/components/accordions) docs for all the supported props.
Check out the [Accordion](/content/components/accordions) docs for all the supported props.
````
`AccordionGroup` does not have any props.
# Accordions
Source: https://mintlify.mintlify.review/content/components/accordions
A dropdown component to toggle content
You can put any content in here. Check out
[AccordionGroup](/content/components/accordion-groups) if you want to group
multiple Accordions into a single display.
```jsx Accordion Example
You can put any content in here.
```
## 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) or SVG code
One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or
"brands"
# Callout Boxes
Source: https://mintlify.mintlify.review/content/components/callouts
Use callouts to add eye-catching context to your content
### Note Callouts
This adds a note in the content
```jsx
This adds a note in the content
```
### Warning Callouts
This raises a warning to watch out for
```jsx
This raises a warning to watch out for
```
### Info Callouts
This draws attention to important information
```jsx
This draws attention to important information
```
### Tip Callouts
This suggests a helpful tip
```jsx
This suggests a helpful tip
```
### Check Callouts
This brings us a checked status
```jsx
This brings us a checked status
```
# Card Groups
Source: https://mintlify.mintlify.review/content/components/card-groups
Show cards side by side in a grid format
The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards on the same column.
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Excepteur sint occaecat cupidatat non proident
```jsx Card Group Example
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit
Ut enim ad minim veniam, quis nostrud exercitation ullamco
Excepteur sint occaecat cupidatat non proident
```
## Props
The number of columns per row
# Cards
Source: https://mintlify.mintlify.review/content/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 Card Group page.
```jsx Card Example
This is how you use a card with an icon and a link. Clicking on this card
brings you to the Card Group page.
```
```jsx Image Card Example
Here is an example of a card with an image
```
### Horizontal Card
Add a `horizontal` property to a card to make it horizontally displayed.
Here is an example of a horizontal card
### Image Card
Add an `img` property to a card to display an image on the top of the card.
Here is an example of a card with an image
## Props
The title of the card
A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}`
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
# Code Blocks
Source: https://mintlify.mintlify.review/content/components/code
Display code with optional syntax highlighting
````md Code Block Example
```javascript Code Block Example
const hello = "world";
```
````
## Basic Code Block
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks.
```
helloWorld();
```
````md
```
helloWorld();
```
````
## Syntax Highlighting
Put the name of your programming language after the three backticks to get syntax highlighting.
We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported.
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````md
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
## Names
Add a title after the programming language to set the name of your code example. The text can be anything as long as its all in one line.
```javascript Code Block Example
const hello = "world";
```
````md Code Block Example
```javascript Code Block Example
const hello = "world";
```
````
## Line Highlighting
Highlight specific lines in your code blocks 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();
```
````md
```javascript Line Highlighting Example {1,3-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
## Expandable
If you have a long code block and `[expandable]` after your title to make it close and expand.
```python library.py [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()
```
````md
```javascript Expandable Example [expandable]
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````
## Code Groups
Want to display multiple code examples in one code box? Check out the Code Group docs:
Read the reference for the Code Group component
# Code Groups
Source: https://mintlify.mintlify.review/content/components/code-groups
The CodeGroup component lets you combine code blocks in a display separated by tabs
You will need to make [Code Blocks](/content/components/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!");
}
}
```
````md 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!");
}
}
```
````
# Expandables
Source: https://mintlify.mintlify.review/content/components/expandables
Toggle to display nested properties.
The full name of the user
Whether the user is over 21 years old
```jsx 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.
# Frames
Source: https://mintlify.mintlify.review/content/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.
```jsx Frame
```
```jsx Frame with Captions
```
# Icons
Source: https://mintlify.mintlify.review/content/components/icons
Use [Font Awesome](https://fontawesome.com/icons) icons anywhere in the doc
```jsx 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
One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
The color of the icon as a hex code (e.g., `#FF5733`)
The size of the icon in pixels
# Mermaid Diagrams
Source: https://mintlify.mintlify.review/content/components/mermaid-diagrams
Display diagrams using Mermaid
````md 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
```
You can create the following using Mermaid diagrams:
* Flowchart
* Sequence diagram
* Class diagram
* State diagram
* Entity relationship diagram
* User journey
* and more
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.
````md
```mermaid
// Your mermaid code block here
```
````
# Parameter Fields
Source: https://mintlify.mintlify.review/content/components/params
Set path, query, and body parameters
`ParamField` components help 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
```jsx Path Example
An example of a parameter field
```
```jsx Query Example
The filtering command used to sort through the users
```
```jsx Body Example
The age of the user. Cannot be less than 0
```
## 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 Fields
Source: https://mintlify.mintlify.review/content/components/responses
Display API response values
The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something.
A response field example
```jsx ResponseField Example
A response field example
```
## Props
The name of the response value.
Expected type of the response value
The default value.
Show "required" beside the field name.
# Steps
Source: https://mintlify.mintlify.review/content/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.
```jsx 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) 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`.
# Sidebar Code Examples
Source: https://mintlify.mintlify.review/content/components/sticky-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](/content/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.
````md 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.
````md ResponseExample Example
```json Response
{ "status": "success" }
```
````
# Tabs
Source: https://mintlify.mintlify.review/content/components/tabs
Toggle content using the Tabs component
You can add any number of tabs.
☝️ Welcome to the content that you can only see inside the first Tab.
✌️ Here's content that's only inside the second Tab.
💪 Here's content that's only inside the third Tab.
```jsx Tabs Example
☝️ Welcome to the content that you can only see inside the first Tab.
✌️ 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.mintlify.review/content/components/tooltips
Show a definition when you hover over text.
Hover over me and see a tooltip in action
```jsx Tooltip Example
Hover over me
```
# Update
Source: https://mintlify.mintlify.review/content/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
```md
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
Label in the changelog, on the sticky left side.
Description below the label in the Changelog preview.
# Local Development
Source: https://mintlify.mintlify.review/development
Preview changes locally to update your docs
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
**Step 1**: Install the Mintlify CLI:
```bash npm
npm i -g mintlify
```
```bash yarn
yarn global add mintlify
```
```bash pnpm
pnpm add -g mintlify
```
**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
```bash
mintlify dev
```
Alternatively, if you do not want to install the CLI globally you can use a run script available:
```bash npm
npx mintlify dev
```
```bash yarn
yarn dlx mintlify dev
```
```bash pnpm
pnpm dlx mintlify dev
```
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
A local preview of your documentation will be available at `http://localhost:3000`.
### Custom Ports
By default, Mintlify uses port 3000. You can customize the port using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
```bash
mintlify dev --port 3333
```
If you attempt to run on a port that's already in use, it will use the next available port:
```md
Port 3000 is already in use. Trying 3001 instead.
```
## Versions
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
```bash npm
npm i -g mintlify@latest
```
```bash yarn
yarn global upgrade mintlify
```
```bash pnpm
pnpm up --global mintlify
```
## Validating Links
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
```bash
mintlify broken-links
```
## Deployment
If the deployment is successful, you should see the following:
## Code Formatting
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider 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.
## Troubleshooting
This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
# Images, Videos, and Embeds
Source: https://mintlify.mintlify.review/image-embeds
Add image, video, and other HTML elements
Mintlify supports files up to 5 MB. To use larger files, consider a storage
service like Cloudinary and embed in your documentation using the URL.
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using 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: autoPlay, playsInline.
## iFrames
Loads another HTML page within the document.
```html
```
Although not required, we recommend adding the `alt` and `title` attributes to
images for better SEO and accessability. Learn more at [image
SEO](https://yoast.com/image-seo-alt-tag-and-title-tag-optimization/).
# Amplitude
Source: https://mintlify.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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.mintlify.review/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"
},
"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"
},
}
```
```json Google Analytics 4 Example
integrations: {
"ga4": {
"measurementId": "G-XXXXXXX"
}
}
```
## FAQ
* `expandable_open`
* `expandable_close`
* `accordion_open`
* `accordion_close`
* `header_nav_item_click`
* `cta_click`
* `scroll_to_bottom`
* `search_close`
* `api_playground_call`
* `search_result_click`
* `chat_enter`
* `chat_followup`
* `chat_completed`
* `code_block_copy`
* `chat_shared`
* `thumb_vote`
* `powered_by_mintlify_click`
* `ai_chat_citation_click`
* `ai_chat_feedback_positive_click`
* `ai_chat_feedback_negative_click`
* `pageview`
# Pirsch
Source: https://mintlify.mintlify.review/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.mintlify.review/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.mintlify.review/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": "required",
"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.mintlify.review/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.mintlify.review/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.mintlify.review/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).
# Speakeasy
Source: https://mintlify.mintlify.review/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.mintlify.review/integrations/sdks/stainless
Automate your SDK example snippets in the API playground
If you use Mintlify's OpenAPI support for your API reference documentation, add the following to your Stainless config:
```yaml openapi.stainless.yml
openapi:
code_samples: mintlify
```
Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so:
```yaml
name: Upload OpenAPI spec to Stainless and (Mintlify) docs repo
on:
push:
branches: [main]
workflow_dispatch:
jobs:
stainless:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Push spec and config to Stainless and outputs documented spec
uses: stainless-api/upload-openapi-spec-action@main
with:
input_path: 'path/to/my-company-openapi.json'
config_path: 'path/to/my-company.stainless.yaml'
output_path: 'path/to/my-company-openapi.documented.json'
project_name: 'my-stainless-project'
- name: Push documented spec to docs repo
uses: dmnemec/copy_file_to_another_repo_action@main
env:
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
with:
source_file: 'config/my-company-openapi.documented.json'
destination_repo: '{DOCS_REPO_NAME}'
destination_folder: 'openapi-specs' # (optional) the folder in the destination repository to place the file in, if not the root directory
user_email: '{EMAIL}' # the email associated with the GH token
user_name: '{USERNAME}' # the username associated with the GH token
commit_message: 'Auto-updates from Stainless'
```
This assumes the following secrets have been [uploaded to your GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
* `secrets.STAINLESS_API_KEY`: Your Stainless API key.
* `secrets.API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with permissions to push to your docs repo.
# Front
Source: https://mintlify.mintlify.review/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.mintlify.review/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": "APP_ID"
}
```
```json Example
"integrations": {
"intercom": "x2pg8cwb"
}
```
# Support Integrations
Source: https://mintlify.mintlify.review/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.mintlify.review/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
```md
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
```md
- 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
```md
- 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.
```md
| Property | Description |
| -------- | ------------------------------------- |
| Name | Full name of user |
| Age | Reported age |
| Joined | Whether the user joined the community |
```
# Migration
Source: https://mintlify.mintlify.review/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 migration for:
}
/>
}
/>
Don't see your docs provider or have a home grown system? We can still help! Please get in touch at [sales@mintlify.com](mailto:sales@mintlify.com).
## 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:
```
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:
```
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.
```
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]
```
# Tabs, Anchors, Dropdowns
Source: https://mintlify.mintlify.review/navigation/divisions
## Tabs
Tabs help distinguish between different topics or sections of your
documentation.
```json docs.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 the tab configuration. We highly recommend that you set an `icon` field as well.
The icon values are [fontawesome icons](https://fontawesome.com/search)
```json docs.json
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"anchor": "API References",
"icon": "sqaure-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"anchor": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
## Dropdowns
Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
We also recommend that you set an icon for each dropdown item ([options](https://fontawesome.com/search)).
```json docs.json
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"dropdown": "API References",
"icon": "sqaure-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"dropdown": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
## Nested Hierarchy
You can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.
```json Top-Level 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 Top-Level 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"
]
}
]
}
]
}
}
```
# Localization
Source: https://mintlify.mintlify.review/navigation/localization
`"languages"` in your `docs.json` can be leveraged to partition your navigation into different languages.
We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), Portuguese (Brazil) (`pt-BR`), and German (`de`).
```json docs.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"]
}
]
}
]
}
}
```
# Overview
Source: https://mintlify.mintlify.review/navigation/overview
The `navigation` property controls the hierarchy of your documentation.
It can contain one of seven properties:
* `pages`
* `groups`
* `anchors`
* `tabs`
* `dropdowns`
* `versions`
* `languages`
These properties all serve the function of partitioning your content and creating a hierarchy so that it's
easier for your users to navigate through your documentation.
If you're currently using the legacy `mint.json` configuration file, please update the CLI:
```sh
npm i -g mintlify@latest
```
And run the new `upgrade` command in your docs repository:
```sh
mintlify upgrade
```
This will generate a `docs.json` based off of your `mint.json`. Then, please delete the `mint.json` file from your repository.
If you want to learn more about the difference between `mint.json` and
`docs.json` checkout our [blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json)
# Pages and Groups
Source: https://mintlify.mintlify.review/navigation/pages
## Pages
If you don't want any hierarchy, you can just define pages within your `navigation` field.
Each entry of the `pages` array must be a path to a file that exists within your repo.
Note you do not need to append `.mdx` to the file paths.
```json
{
"navigation": {
"pages": [
"overview",
"quickstart",
"advanced/components",
"advanced/integrations"
]
}
}
```
## Groups
Groups allow you to group your pages. Groups can also be nested within each other.
```json
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
}
]
},
{
"group": "Writing Content",
"pages": ["writing-content/page", "writing-content/text"]
}
]
}
}
```
# Versions
Source: https://mintlify.mintlify.review/navigation/versions
`"versions"` in your `docs.json` can be leveraged to partition your navigation into different versions.
```json docs.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"]
}
]
}
]
}
}
```
You can also add versioning to a specific section of your docs by nesting a version.
```json docs.json [expandable]
{
"tabs": [
{
"tab": "Guides",
"pages": ["overview", "quickstart"]
},
{
"tab": "SDKs",
"versions": [
{
"version": "latest",
"anchors": [
{
"anchor": "Javascript",
"pages": ["sdk/js/create", "sdk/js/edit", "sdk/js/delete"]
},
{
"anchor": "Python",
"pages": ["sdk/py/create", "sdk/py/edit", "sdk/py/delete"]
}
]
}
]
}
]
}
```
# Page Titles and Metadata
Source: https://mintlify.mintlify.review/page
Setting the title and metadata for navigation and SEO
## The Basics
Each page is an MDX file that should begin with the following metadata syntax
with `---` at the start and end:
```md Schema
---
title: "title of the page"
---
```
```md Example
---
title: "Page"
---
```
Mintlify will use the name of the file if you forget to include a title.
Other metadata goes in between the same `---` lines. For example, this page uses
this metadata:
```md
---
title: "Page Titles and Metadata"
description: "Setting the title and metadata for navigation and SEO"
---
```
## Descriptions
You can show a description that shows directly under the title with the
`description` metadata.
```md
description: "Your description goes here."
```
## Sidebar Title
You can show a different title in the navigation with the `sidebarTitle`
metadata. This is useful if your title is long and you want something shorter in
the navigation links.
```md
---
title: "Your very long page title you want to shorten"
sidebarTitle: "Short title"
---
```
## Sidebar Icons
Want an icon for your sidebar item like the ones in
[components](/content/components/accordions)? You can set an `icon` attribute in
the metadata! All icons from [Font Awesome](https://fontawesome.com/icons) are
available for us. You can also set an icon type (optional). If not set, the icon
type will be regular.
```md
---
title: "Code Block"
icon: "rectangle-code"
iconType: "solid"
---
```
## 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 playgrounds in [our demo](/api-playground).
```md Schema
api or openapi: method endpoint
```
```md API Example
api: "GET /users"
```
```md OpenAPI Example
openapi: "GET /users"
```
## 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 with the default table of contents (if headings are present) and other standard
elements, providing a typical layout without any special adjustments.
```md
---
title: "Page with no ToC"
---
```
### 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 other content.
```md
---
title: "Page with no ToC"
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.
```md
---
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.
```md
---
mode: "center"
---
```
## External Links
If you want the sidebar to open an external URL, you can set the `url` metadata
in any page.
```md
---
title: "Page that goes to external link"
url: "https://www.npmjs.com/package/mintlify"
---
```
## 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. Meta tags with colons need to be wrapped in
quotes.
```md
"twitter:image": "/images/your-photo.jpg"
```
See [our SEO page](/settings/seo) for all supported meta tags.
# Quickstart
Source: https://mintlify.mintlify.review/quickstart
Start building modern documentation in under five minutes
## Getting Started
Welcome! Follow the instructions below to learn how to deploy, update and
supercharge your documentation with Mintlify.
### Creating the Repository
Mintlify docs are rendered from MDX files and configurations defined in our
[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository.
If you want your docs to live alongside your code as a monorepo setup, you
can: 1. Move your docs content to your monorepo. 2. Specify the path to your
`docs.json` in the
[dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings)
### Updating the Content
Mintlify enables you to easily customize the style, structure, and content of
your docs.
1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
3. Use your favorite IDE to open the repository.
4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`.
Learn more about this in our [local development guide](/development).
Learn more about how to use the web editor on our [guide](/web-editor).
Easily customize colors, logos and buttons among other configurations in our `docs.json` file. Start with these basic configurations:
```json
"name": "Your Company"
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg",
"href": "https://yourcompany.com"
},
"favicon": "/favicon.svg",
"colors": {
"primary": "#2AB673",
"light": "#55D799",
"dark": "#117866",
},
```
A full list of supported configurations can be found at [global settings](/settings/global).
Add content with simple MDX files. Initiate your pages with this template:
```md
---
title: "Page Title"
sidebarTitle: "Sidebar title (optional - if different from page title)"
description: "Subtitle (optional)"
---
```
Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components).
Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com).
You can easily set up your API references using an OpenAPI document.
1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `docs.json` with a URL.
```json
"openapi": "link-to-your-openapi-file"
```
2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as:
```bash
npx @mintlify/scraping@latest openapi-file
```
3. Finally, include the generated endpoint MDX files to your `docs.json` under `navigation`.
For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview).
Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics).
We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview).
We provide a white-glove migration service as part of our Enterprise plan.
Interested? You can request it by [contacting us](mailto:sales@mintlify.com).
### Publishing
Integrate your docs into your website by hosting them on a custom domain. This is included in the free plan.
Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.
Congrats! You've set up your Mintlify Docs and it's looking amazing! Need
support or want to give some feedback? You can join our
[community](https://mintlify.com/community) or drop us an email at
[support@mintlify.com](mailto:support@mintlify.com).
# Reusable Snippets
Source: https://mintlify.mintlify.review/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}.
```
### Reusable components
1. Inside your snippet file, create a component that takes in props by exporting
your component in the form of an arrow function.
```typescript snippets/custom-component.mdx
export const MyComponent = ({ title }) => (
{title}
... snippet content ...
);
```
MDX does not compile inside the body of an arrow function. Stick to HTML
syntax when you can or use a default export if you need to use MDX.
2. Import the snippet into your destination file and pass in the props
```typescript destination-file.mdx
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
```
### Client-Side Content
By default, Mintlify employs server-side rendering, generating content
at build time. For client-side content loading, ensure to verify the
`document` object's availability before initiating the rendering process.
```typescript snippets/client-component.mdx
{/* `setTimeout` simulates a React.useEffect, which is called after the component is mounted. */}
export const ClientComponent = () => {
if (typeof document === "undefined") {
return null;
} else {
setTimeout(() => {
const clientComponent = document.getElementById("client-component");
if (clientComponent) {
clientComponent.innerHTML = "Hello, client-side component!";
}
}, 1);
return
}
}
```
# Authentication
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication
Guarantee privacy of your docs by authenticating users
Authentication offers full privacy for all of your
documentation content by requiring users to authenticate before viewing any content, such as:
* Documentation page content
* Images used in documentation pages
* Search results
* AI chat interactions
You can authenticate users through handshake methods such as:
* [Password](./authentication-setup/password)
* [JWT](./authentication-setup/jwt)
* [OAuth](./authentication-setup/oauth)
* [Mintlify dashboard](./authentication-setup/mintlify)
Authentication is similar to our [Personalization](./personalization) offering, but with guaranteed privacy. In addition
to securing your documentation content, all features that are available via
Personalization are also available via Authentication.
Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization).
# Choosing a Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-setup/choosing-a-handshake
How to decide which Handshake method is right for your docs
This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake).
Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods:
1. **Password**: Configure a set of global passwords for your documentation site.
2. **JWT**: Use your own login flow to authenticate your users via a JWT in the URL.
3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow.
4. **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required.
## Prerequisites
* Your security requirements allow for password sharing between documentation readers.
* You have some existing login flow.
* You can add a final step in this login flow that creates a JWT and redirects to the docs.
* You have an existing OAuth server that supports the Authorization Code flow.
* You can create a new API endpoint that can be accessed by the returned OAuth access token.
* Your documentation readers are also your documentation editors.
## Pros & Cons
Pros:
* Super simple setup
* No configuration required for adding new users - just share the password
Cons:
* Difficult to revoke access to your docs without resetting the password
* Lose personalization features, as there is no way to differentiate users with the same password
Pros:
* Reduced risk of API endpoint abuse
* Zero CORS configuration
* No restrictions on API URLs
Cons:
* Must be able to hook into your existing login flow
Pros:
* Heightened security standard
Cons:
* Requires significant work if setting up OAuth server for the first time
* Might be overkill for some applications
Pros:
* Zero-config setup
Cons:
* Requires all docs readers to have an account in your Mintlify dashboard
# JWT Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-setup/jwt
Use a customized login flow to authenticate users
This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
## Implementation
Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
Create a login flow that does the following:
* Authenticate the user
* Create a JWT containing the authenticated user's info in the [User](../sending-data) format
* Sign the JWT with the 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
Return to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
## Example
I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
to be completely separate from my dashboard (or I don’t have a dashboard at all).
To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
for my users. At the end of this login flow, once I have verified the identity of the user,
I create a JWT containing the user’s custom data according to Mintlify’s specification.
I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
I then go to the dashboard settings and enter `https://foo.com/docs-login` for the
Login URL field.
Here's what the code might look like:
```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 specific page, Mintlify preserves their intended destination through a redirect flow:
1. The user attempts to visit a certain page (e.g., `/quickstart`)
2. Mintlify redirects them to your login URL and adds the (relative) original destination as a `redirect` query parameter
Example:
* Original request: [`https://docs.foo.com/quickstart`](https://docs.foo.com/quickstart)
* Redirect to login: [`https://foo.com/docs-login?redirect=%2Fquickstart`](https://foo.com/docs-login?redirect=%2Fquickstart)
After successful authentication, you can include this same `redirect` parameter in your JWT callback URL to send users to their intended destination:
`https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`
# Mintlify Auth Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-setup/mintlify
Use Mintlify to authenticate users
The Mintlify Auth Handshake is available only for Authentication, *not*
Personalization.
You can use Mintlify to authenticate and manage access to your documentation. Anyone that can access your dashboard will automatically be able to see your documentation.
This handshake method also enables private preview deployments, so that only Mintlify authenticated users will be able to access your preview deployments.
Authentication is available only by request. Please{" "}
contact sales for access. After we've
enabled access, you can follow the implementation instructions.
### Example
I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
to be internal, and the people that will be viewing my docs are the same people that
contribute to my docs.
To set up authentication with Mintlify, I can go to my [dashboard settings](https://dashboard.mintlify.com/products/authentication)
and enable Authentication with the Mintlify Auth Handshake.
I can then ensure that anyone that should be able to read the docs has been added as a user in
my [dashboard settings](https://dashboard.mintlify.com/settings/organization/members).
## Implementation
Go to your [Mintlify dashboard
settings](https://dashboard.mintlify.com/products/authentication) and select
the Mintlify Auth Handshake.
Ensure that any users that should be able to view your documentation have
been added as users in your [Mintlify dashboard
settings](https://dashboard.mintlify.com/settings/organization/members).
# OAuth 2.0 Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-setup/oauth
Integrate with your OAuth server to enable user login via the Authorization Code flow
This is the documentation for the OAuth **Authentication** Handshake. The steps for setting up the [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) are slightly different.
If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.
## Implementation
Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
* **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
* **Client ID**: An ID for the OAuth 2.0 client to be used.
* **Scopes**: An array of scopes that will be requested.
* **Token URL**: The base URL for the token exchange request.
* **Info API URL** (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty.
Copy the Redirect URL listed in the [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format.
Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL
to your OAuth configuration.
## Example
I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
To set up authentication with Mintlify, I create an endpoint `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 according to Mintlify’s specification.
I then go to the dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
* **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`
Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
# Password Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-setup/password
Use a set of shared passwords to authenticate users
This is the documentation for the Password **Authentication** Handshake. The
Password Handshake is not available for Personalization.
If you don't have strict security requirements, or you don't want to manage a
database of documentation readers, you can use a set of shared passwords to
protect your docs.
Authentication is available only by request. Please{" "}
contact our sales team for access.
After we've enabled access, you can follow the implementation instructions.
## Implementation
Go to your [dashboard
settings](https://dashboard.mintlify.com/products/authentication) and create
a password.
Securely share the password with your documentation readers. That's it!
## Example
I want to set up authentication for my docs hosted at `docs.foo.com`. I don't want
to have to keep track of who can and cannot access the docs. My main use case for
authentication is to prevent competitors from snooping - password sharing is secure
enough for my team.
To set up authentication with Mintlify, I go to my Mintlify dashboard and add at
least one password. I then share that password, along with the private docs URL,
with potential customers.
# Auth vs Personalization
Source: https://mintlify.mintlify.review/settings/authentication-personalization/authentication-vs-personalization
How to determine which product is best for you
Mintlify offers both Authentication and Personalization. For the most part, Authentication is
just Personalization + privacy. However, there are some key differences that are important to
be aware of, from most important to least:
### Security Guarantees
Authentication is a fully-fledged private documentation solution. Every aspect of your docs,
including page content, images, search results, and AI chat features, are completely inaccessible to
unauthenticated users.
Personalization, on the other hand, offers no security guarantees for your documentation content.
All page content, images, search results, and AI chat features can be accessed by the public. Even
if you are using the hidden pages feature of Personalization, a motivated attacker would still
be able to access the content of a hidden page.
### Handshake Methods
Due to the difference in security requirements for Authentication and Personalization, different
handshake methods are available for each. Both methods offer a JWT and OAuth Handshake, although
the setup steps are slightly different.
Authentication offers two additional Handshake methods:
* **Password Handshake**, which protects your website with a single configurable global password.
* **Mintlify Auth Handshake**, which will allow users to view your documentation only if they have
access to your dashboard.
Personalization offers one additional Handshake method:
* **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint
that returns data for already-authenticated users.
# Partial Authentication
Source: https://mintlify.mintlify.review/settings/authentication-personalization/partial-authentication
Authenticate users to view only certain pages
Partial Authentication allows you to authenticate users to view only certain pages.
You can authenticate users through handshake methods such as:
* [Password](./authentication-setup/password)
* [JWT](./authentication-setup/jwt)
* [OAuth](./authentication-setup/oauth)
* [Mintlify dashboard](./authentication-setup/mintlify)
Partial Authentication shares all the same features as [Authentication](./authentication), but with the ability to allow unauthenticated users to view certain pages.
By default, all pages are protected. You can specify which pages should be publicly accessible by adding the `public` property to the page's frontmatter.
```mdx
---
title: "My Page"
public: true
---
```
# Personalization
Source: https://mintlify.mintlify.review/settings/authentication-personalization/personalization
A list of features unlocked with Personalization
Personalization refers to a suite of features that allow you to customize your
documentation experience based on some information about the user. There are
three major features of Personalization:
* **Customize MDX content** with a user's information, such as their name, plan, or title.
* **Prefill API keys** in the API Playground for streamlined use.
* **Selectively show pages** in the navigation based on a user's groups.
## How to Use
### Customizing MDX Content
When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example:
Hello, {user.name ?? 'reader'}!
```jsx
Hello, {user.name ?? 'reader'}!
```
This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan:
Personalization 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
Personalization 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 after a user has logged in. 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, e.g. `{user.org?.plan}`
### Prefilling API Keys
If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.
### Showing/Hiding Pages
By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata.
When determining which pages to show to the user, Mintlify will check which groups the user belongs to.
If the user is not in any of the groups listed in the page metadata, the page will not be shown.
```md
---
title: "Managing Your Users"
description: "Adding and removing users from your organization"
groups: ["admin"]
---
```
Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata:
| | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User |
| :------------------------------ | :------------------: | :------------------: | :-------------------------: |
| `groups` not in metadata | ✅ | ✅ | ✅ |
| `groups: []` in metadata | ❌ | ❌ | ❌ |
| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ |
Note that an empty array in the page metadata is interpreted as "No groups
should see this page."
# Choosing a Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/personalization-setup/choosing-a-handshake
How to decide which Handshake method is right for your docs
This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication-setup/choosing-a-handshake).
Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods:
1. **Shared Session**: Utilize the same session token used by your dashboard to authenticate users.
2. **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL.
3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the PKCE flow.
## Prerequisites
* You have a dashboard or other user portal hosted at your domain.
* Your users' session credentials are stored as cookies.
* You can create a new API endpoint at the same origin or a subdomain of 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 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`
* You have some existing login flow.
* You can add a final step in this login flow that creates a JWT and redirects to the docs.
* You have an existing OAuth server that supports the PKCE flow.
* You can create a new API endpoint that can be accessed by the returned OAuth access token.
## Pros & Cons
Pros:
* Users that are logged into your dashboard are automatically logged into your docs
* Your users' sessions are persistent, meaning you can refresh data without requiring additional login
* Minimal setup required
Cons:
* Your docs will make a request to your backend, which may be undesirable
* You must have a dashboard that uses session authentication
* CORS configuration is usually required
Pros:
* Reduced risk of API endpoint abuse
* Zero CORS configuration
* No restrictions on API URLs
Cons:
* Must be able to hook into your existing login flow
* Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
* Every time you want to refresh user data, your users must re-login to your docs
* If your users' data changes frequently, you must require your users to log in frequently or risk having stale data in the docs
* If your users' data rarely changes, this shouldn't be a problem
Pros:
* Heightened security standard
* No restrictions on API URLs
Cons:
* Requires significant work if setting up OAuth server for the first time
* Dashboard sessions and docs authentication are completely decoupled, so users will need to log in to your dashboard and your docs separately
* Might be overkill for some applications
# JWT Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/personalization-setup/jwt
Use a customized login flow to authenticate users
This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different.
If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL.
## Implementation
Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
Create a login flow that does the following:
* Authenticate the user
* Create a JWT containing the authenticated user's info in the [User](../sending-data) format
* Sign the JWT with the secret key, using the EdDSA algorithm
* Create a redirect URL back to your docs, including the JWT as the hash
Return to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings.
## Example
I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
to be completely separate from my dashboard (or I don’t have a dashboard at all).
To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
for my users. At the end of this login flow, once I have verified the identity of the user,
I create a JWT containing the user’s custom data according to Mintlify’s specification.
I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.
I then go to the dashboard settings and enter `https://foo.com/docs-login` for the
Login URL field.
Here's what the code might look like:
```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, 'EdDSA');
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: 'EdDSA' })
.setExpirationTime('10 s')
.sign(signingKey);
return res.redirect(`https://docs.foo.com#${jwt}`);
}
```
## Preserving Anchors
Post-login, if you'd like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.
Example:
* Original: `https://docs.foo.com/quickstart#step-one`
* Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
# OAuth 2.0 Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/personalization-setup/oauth
Integrate with your OAuth server to enable user login via the PKCE flow
This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different.
If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.
## Implementation
Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint.
Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
* **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
* **Client ID**: An ID for the OAuth 2.0 client to be used.
* **Scopes**: An array of scopes that will be requested.
* **Token URL**: The base URL for the token exchange request.
* **Info API URL**: The endpoint that will be hit to retrieve user info.
Copy the Redirect URL listed in the [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
## Example
I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
To set up authentication with Mintlify, I create an endpoint `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 according to Mintlify’s specification.
I then go to the dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
* **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`
Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
# Shared Session Handshake
Source: https://mintlify.mintlify.review/settings/authentication-personalization/personalization-setup/shared-session
Seamlessly share user sessions between your dashboard and your docs
This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication.
This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
## Implementation
Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User](../sending-data) format.
If the API domain does not *exactly match* the docs domain:
* Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`)
* Ensure your API’s `Access-Control-Allow-Credentials` header is `true`
These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.
Go to your [dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings.
## Examples
### Dashboard at subdomain, docs at subdomain
I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`.
To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.
I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
### Dashboard at subdomain, docs at root
I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.
I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
### Dashboard at root, docs at root
I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.
I then go to the dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.
# Sending Data
Source: https://mintlify.mintlify.review/settings/authentication-personalization/sending-data
The shape of user data you can use to personalize your docs
Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:
```tsx
type User = {
expiresAt?: number;
groups?: string[];
content?: Record;
apiPlaygroundInputs?: {
header?: Record;
query?: Record;
cookie?: Record;
server?: Record;
};
};
```
The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted.
For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks.
A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown.
A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!`
User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value.
The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section.
# Redirects and Broken Links
Source: https://mintlify.mintlify.review/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](/development) and run the command:
```bash
mintlify 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.mintlify.review/settings/ci
Add broken links, linting, and grammar checks to the updating process
This feature is only available for customers on paid plans and for GitHub. Support for other platforms is coming soon.
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 commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.
# Custom Domain
Source: https://mintlify.mintlify.review/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:
```
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 CSS & JS
Source: https://mintlify.mintlify.review/settings/custom-scripts
Fully customize your documentation with custom CSS & JS
Add custom CSS & JS to your documentation to fully customize the look and feel.
## Custom CSS
Add any number of CSS files to your repository and the defined class names will be applied and available across 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
Mintlify has a set of common identifiers to help you tag important elements of the UI. Some, but not all are listed in the following:
`#topbar-cta-button` `#navbar` `#sidebar` `#content-area` `#table-of-contents`
Use inspect element to find references to elements you're looking to
customize.
References and the styling of common elements are subject to change as the
platform evolves. Please use custom styling with caution.
## Custom JS
Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `
In the details of the git check warning, you'll find the link to upgrade your plan. You can also upgrade your plan on the [dashboard](https://dashboard.mintlify.com) to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.
Learn more about our pricing [here](https://mintlify.com/pricing).
# Single Sign-On (SSO)
Source: https://mintlify.mintlify.review/advanced/dashboard/sso
Customize how your team can login to your admin dashboard
Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us!
## 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](/advanced/rest-api/update/trigger).
## Chat API key
The Chat API allows you to embed the AI chat 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.
If you have trouble setting up a custom subdirectory,
[contact our support team](mailto:sales@mintlify.com) and we'll walk you through
upgrading your hosting with us.
### Edit Worker Script
Click on `Edit Code` and add the following script into the worker's code.
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.
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](/web-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.
## 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();
```
````md
```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.
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](/content/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)
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.
## Captions
You can add additional context to an image using the optional `caption` prop.
## Props
```
```jsx Frame with Captions
## 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
## Code Formatting
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider 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.
## Troubleshooting
```
### Related
For more information, we recommend the following sections:
```json docs.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 the tab configuration. We highly recommend that you set an `icon` field as well.
The icon values are [fontawesome icons](https://fontawesome.com/search)
```json docs.json
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"anchor": "API References",
"icon": "sqaure-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"anchor": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
## Dropdowns
Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
We also recommend that you set an icon for each dropdown item ([options](https://fontawesome.com/search)).
```json docs.json
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
}
{
"dropdown": "API References",
"icon": "sqaure-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
{
"dropdown": "Blog",
"href": "https://external-link.com/blog"
}
]
}
```
## Nested Hierarchy
You can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.
## Getting Started
Welcome! Follow the instructions below to learn how to deploy, update and
supercharge your documentation with Mintlify.
### Creating the Repository
Mintlify docs are rendered from MDX files and configurations defined in our
[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
## 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:
```
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 CSS & JS
Source: https://mintlify.mintlify.review/settings/custom-scripts
Fully customize your documentation with custom CSS & JS
Add custom CSS & JS to your documentation to fully customize the look and feel.
## Custom CSS
Add any number of CSS files to your repository and the defined class names will be applied and available across 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
Mintlify has a set of common identifiers to help you tag important elements of the UI. Some, but not all are listed in the following:
`#topbar-cta-button` `#navbar` `#sidebar` `#content-area` `#table-of-contents`