# Custom CSS

Fully customize your documentation with custom CSS

<Check>
  Custom CSS is available as an add-on to the [pro plan](https://mintlify.com/pricing).
</Check>

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`

<Tip>
  Use inspect element to find references to elements you're looking to
  customize.
</Tip>

<Warning>
  References and the styling of common elements are subject to change as the
  platform evolves. Please use custom styling with caution.
</Warning>


# Custom JS

Add JavaScript functionality globally

<Check>
  Custom JS is available as an add-on to the [pro plan](https://mintlify.com/pricing).
</Check>

Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `<script>` tag with JS code into every page.

## Adding Custom JavaScript

Any `.js` file inside the content directory of your docs will be included in every documentation page. For example, you can add the following `ga.js` file to enable [Google Analytics](https://marketingplatform.google.com/about/analytics) across the entire documentation.

```js
window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');
```

<Warning>
  Please use with caution to not introduce security vulnerabilities.
</Warning>


# Introduction



<Check>
  The Mintlify REST API is only available on the startup plan and above.
</Check>

Leverage the external API to programmatically trigger an update when desired.
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/integrations). The API key is
associated with the entire org and can be used across multiple deployments.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/external-api-key.png" />
</Frame>


# Trigger an update

POST /project/update/{projectId}
Trigger an update after updating your OpenAPI document by calling this endpoint in a CI check.



# Get the status of an update

GET /project/update-status/{statusId}



# Cloudflare

Host documentation at a /docs subpath using Cloudflare Workers

export const platform_0 = "Cloudflare"

<Info>
  **Prerequisite**: Your primary domain (company.com) is hosted on {platform_0}
  and you are on the [Mintlify Pro plan or above](https://mintlify.com/pricing).
</Info>

## Create Cloudflare Worker

Navigate to the `Workers & Pages > Create application > Create worker`. You
should be able to presented with the following screen where you can create a new
Cloudlfare worker.

<Frame>
  <img alt="Create a Cloudflare worker" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudflare/worker.png" />
</Frame>

### 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.

<Frame>
  <img alt="Cloudflare worker custom domain" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudflare/custom-domain.png" />
</Frame>

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.

<Frame>
  <img alt="Cloudflare edit code" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudflare/edit-code.png" />
</Frame>

<Tip>
  Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and
  `CUSTOM_URL` with your website's base URL.
</Tip>

```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).


# Route 53 and Cloudfront

Host documentation at a /docs subdirectory using AWS services

export const platform_0 = "AWS Services"

<Info>
  **Prerequisite**: Your primary domain (company.com) is hosted on {platform_0}
  and you are on the [Mintlify Pro plan or above](https://mintlify.com/pricing).
</Info>

## Create Cloudfront Distribution

Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution`

<Frame>
  ![Cloudfront Create Distribution](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/create-distribution.png)
</Frame>

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

<Frame>![Cloudfront Origin name](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/origin-name.png)</Frame>

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

<Frame>
  ![Cloudfront Caching policy](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/caching-policy.png)
</Frame>

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

<Frame>
  ![Cloudfront Caching
  policy](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/enable-security-protections.png)
</Frame>

The remaining settings should be default. Click `Create distribution`.

## Add Default Origin

After creating the distribution, navigate to the `Origins` tab.

<Frame>![Cloudfront Origins](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/origins.png)</Frame>

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.

<Info>
  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.
</Info>

<Note>
  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
</Note>

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**.

<Frame>
  ![Cloudfront Default Origins](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/default-origin.png)
</Frame>

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`)

<Frame>![Cloudfront Behavior 1](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/behavior-1.png)</Frame>

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.

<Frame>![Cloudfront Behavior 2](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/behavior-2.png)</Frame>

### `Default (*)`

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

<Frame>
  ![Cloudfront Behavior Default 1](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/default-behavior-1.png)
</Frame>

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`).

<Frame>
  ![Cloudfront Behavior Default 2](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/default-behavior-2.png)
</Frame>

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.

<Frame>
  ![Cloudfront Preview
  distribution](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/preview-distribution.png)
</Frame>

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.

<Note>
  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)
</Note>

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`

<Frame>
  ![Route 53 create record](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/route53-create-record.png)
</Frame>

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

<Frame>
  ![Route 53 create record alias](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/cloudfront/create-record-alias.png)
</Frame>

Click `Create records`.

<Note>
  You may need to remove the existing A record if one currently exists.
</Note>

And voila! You should be able to have your documentation served at `/docs` for your primary domain.


# Vercel

Host documentation at a /docs subpath using Vercel

export const platform_0 = "Vercel"

<Info>
  **Prerequisite**: Your primary domain (company.com) is hosted on {platform_0}
  and you are on the [Mintlify Pro plan or above](https://mintlify.com/pricing).
</Info>

## 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*"
    }
  ]
}
```

<Note>
  For more information, you can also refer to Vercel's offical guide on check
  out the [Project Configuration:
  Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
</Note>


# Choosing an Auth Method

How to decide which auth method is right for your docs

Before your users can access personalized content, they must be authenticated. Mintlify supports two methods of authenticating users:

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

<Tabs>
  <Tab title="Shared Session">
    *   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`
  </Tab>

  <Tab title="JWT">
    *   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.
  </Tab>

  <Tab title="OAuth 2.0">
    *   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.
  </Tab>
</Tabs>

## Pros & Cons

<Tabs>
  <Tab title="Shared Session">
    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
  </Tab>

  <Tab title="JWT">
    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
  </Tab>

  <Tab title="OAuth 2.0">
    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
  </Tab>
</Tabs>


# JWT Auth

Use a customized login flow to authenticate users

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

<Steps>
  <Step title="Generate a private key">
    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
  </Step>

  <Step title="Create a login flow">
    Create a login flow that does the following:

    *   Authenticate the user
    *   Create a JWT containing the authenticated user's info in the [UserInfo](./sending-data) format
    *   Sign the JWT with the secret, using the ES256 algorithm
    *   Create a redirect URL back to your docs, including the JWT as the hash
  </Step>

  <Step title="Configure your User Auth settings">
    Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the login URL to your User Auth settings.
  </Step>
</Steps>

## 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 Mintlify 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, 'ES256');

export async function handleRequest(req: Request, res: Response) {
  const userInfo = {
    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(userInfo)
    .setProtectedHeader({ alg: 'ES256' })
    .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

Integrate with your OAuth server to enable user login via the PKCE flow

If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.

## Implementation

<Steps>
  <Step title="Create your Info API">
    Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](./sending-data) format. Take note of the scope or scopes required to access this endpoint.
  </Step>

  <Step title="Configure your User Auth settings">
    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-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.
  </Step>

  <Step title="Configure your OAuth client">
    Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server.
  </Step>
</Steps>

## 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 Mintlify dashboard settings, navigate to the User Auth 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.


# Introduction

Give your users a personalized docs experience

User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. your users.

Example use cases:

1.  **Customize MDX content** with a user's information, such as their name, plan, or title.
2.  **Prefill API keys** in the API Playground for streamlined use.
3.  **Selectively show pages** in the navigation based on a user's groups.

## What *isn't* User Auth

At this time, User Auth is not meant for the following use cases:

1.  **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it.
2.  **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data.

<Note>If you are interested in private docs content, [contact our team](mailto:sales@mintlify.com) to explore solutions.</Note>

## How to Use

### Customizing MDX Content

When writing content, you can use the `userContext` variable to access the information you have sent to your docs. Here's a simple example:

Hello, {userContext.name ?? 'reader'}!

```jsx
Hello, {userContext.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 User Auth feature based on the customer's existing plan:

User Auth is an enterprise feature. {
  userContext.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : userContext.org.plan !== 'enterprise'
      ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:sales@mintlify.com">contact our sales team</a>.</>
      : <>To request this feature for your enterprise org, <a href="mailto:sales@mintlify.com">contact our team</a>.</>
}

```jsx
User Auth is an enterprise feature. {
  userContext.org === undefined
    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
    : userContext.org.plan !== 'enterprise'
      ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:sales@mintlify.com">contact our sales team</a>.</>
      : <>To request this feature for your enterprise org, <a href="mailto:sales@mintlify.com">contact our team</a>.</>
}
```

<Note>
  The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}`
</Note>

### 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 UserInfo and page metadata:

|                                 | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo |
| :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: |
| `groups` not in metadata        |             ✅            |             ✅            |                ✅                |
| `groups: []` in metadata        |             ❌            |             ❌            |                ❌                |
| `groups: ['admin']` in metadata |             ❌            |             ❌            |                ✅                |

<Note>Note that an empty array in the page metadata is interpreted as "No groups should see this page."</Note>


# Sending Data

The types and shape of user data you can send to Mintlify

Depending on your authentication configuration, 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 UserInfo = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};
```

<ParamField path="expiresAt" type="number">
  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.
  <Warning><b>For JWT Auth:</b> 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.</Warning>
</ParamField>

<ParamField path="groups" type="string[]">
  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.
</ParamField>

<ParamField path="content" type="object">
  A bag of values that can be accessed from within MDX content using the `userContext` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {userContext.firstName}!`
</ParamField>

<ParamField path="apiPlaygroundInputs" type="object">
  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.

  <Note>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.</Note>
</ParamField>


# Shared Session Auth

Seamlessly share user sessions between your dashboard and your docs

This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.

## Implementation

<Steps>
  <Step title="Create your Info API">
    Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./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`

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Configure your User Auth settings">
    Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings.
  </Step>
</Steps>

## 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 Mintlify 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 Mintlify 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 Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.


# Chat Widget



Integrate the Mintlify widget into your products to offer users quick access to AI-powered chat with your docs content as the knowledge base.

![widget](https://mintlify-assets.b-cdn.net/widget/hero.webp)

## Getting started

First, generate an API key in [the Mintlify dashboard](https://dashboard.mintlify.com/chat/widget-auth).

![widget](https://mintlify-assets.b-cdn.net/widget/key.webp)

## Installation

Add the widget by adding these script tags into your site's `<head>...<head/>` tag.

```html
<script>
    window.mintlifyWidgetSettings = {
        connection: {
            apiKey: 'Your API key here'
        },
    };
</script>
<script>
    (function () {
        if (!document.getElementById('mintlify-widget')) {
            var script = document.createElement('script');
            script.id = 'mintlify-widget';
            script.src = 'https://unpkg.com/@mintlify/widget@^0';
            script.onload = () => MintlifyWidget.init();
            document.head.appendChild(script);
        }
    })();
</script>
```

To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react` [package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application:

```jsx
<MintlifyWidget
    connection={{
        apiKey: 'Your API key here',
    }}
/>
```

## Usage

In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props:

| Prop         | Type                                                                | Description                                                |
| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
| `connection` | [MintlifyWidgetConnectionProps](#mintlifywidgetconnectionProps)     | Information needed to connect to our API. Required.        |
| `display?`   | [MintlifyWidgetDisplayProps](#mintlifywidgetdisplayProps)           | Configurations for the widget appearance and interactions. |
| `tracking?`  | [MintlifyWidgetTrackingFunctions](#mintlifywidgettrackingfunctions) | Callback functions for tracking analytics.                 |

### MintlifyWidgetConnectionProps

| Prop     | Type     | Description                                                 |
| -------- | -------- | ----------------------------------------------------------- |
| `apiKey` | `string` | Widget API key generated from Mintlify dashboard. Required. |
| `url?`   | `string` | Used for internal testing only                              |

### MintlifyWidgetDisplayProps

| Prop          | Type                                                                    | Description                                                 |
| ------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| `trigger?`    | [MintlifyWidgetDisplayTriggerProps](#mintlifywidgetdisplaytriggerprops) | Appearance of the trigger.                                  |
| `colors?`     | [MintlifyWidgetDisplayColorsProps](#mintlifywidgetdisplaycolorsprops)   | Colors used across the widget.                              |
| `chat?`       | [MintlifyWidgetDisplayChatProps](#mintlifywidgetdisplaychatprops)       | Configs specific to AI chat.                                |
| `isDarkMode?` | `boolean`                                                               | Controlled dark mode appearance. Defaults to OS preference. |

#### MintlifyWidgetDisplayTriggerProps

| Prop          | Type                                 | Description                                                                                                                |
| ------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `type?`       | `'button'`\|`'input'`                | Type of the trigger to display. Defaults to `button`.                                                                      |
| `label?`      | `string`                             | Label displayed in the trigger. Defaults to `Get help` for the button trigger and `Ask anything...` for the input trigger. |
| `buttonIcon?` | `'chat'`\|`'sparkles'`\|`'mintlify'` | Icon used in the trigger. Only available for the `button` trigger. Defaults to `chat`.                                     |
| `iconOnly?`   | `boolean`                            | Only show icon in the trigger or not. Defaults to `false`.                                                                 |

Here is an overview of what the trigger looks like with different configurations.

| `type='input'` |                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------- |
|                | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/input.png" /> |

| `type='button'`  | `'chat'`                                                                                                | `'sparkles'`                                                                                                | `'mintlify'`                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `iconOnly=false` | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-chat.png" />          | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-sparkles.png" />          | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-mintlify.png" />          |
| `iconOnly=true`  | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-chat-iconOnly.png" /> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-sparkles-iconOnly.png" /> | <img style={{height:'80px'}} src="https://mintlify-assets.b-cdn.net/widget/button-mintlify-iconOnly.png" /> |

#### MintlifyWidgetDisplayColorsProps

| Prop            | Type     | Description                                              |
| --------------- | -------- | -------------------------------------------------------- |
| `primary?`      | `string` | Primary color used in the widget. Defaults to `#0D9373`. |
| `primaryLight?` | `string` | Primary color in dark mode. Defaults to `#55D799`.       |

#### MintlifyWidgetDisplayChatProps

| Prop                     | Type       | Description                                                        |
| ------------------------ | ---------- | ------------------------------------------------------------------ |
| `openCitationInSameTab?` | `boolean`  | Open the citation url in the same tab or not. Defaults to `false`. |
| `exampleQueries?`        | `string[]` | Example queries to prompt the user to ask. Defaults to `[]`.       |

### MintlifyWidgetTrackingFunctions

| Prop                  | Type                                       | Description                                        |
| --------------------- | ------------------------------------------ | -------------------------------------------------- |
| `trackChatEnter`      | `()=> void`                                | Triggered when the user opens the chat widget.     |
| `trackCitationClick`  | `(title: string, url: string)=> void`      | Triggered when the user clicks on a citation.      |
| `trackChatThumbsUp`   | `(query: string, response: string)=> void` | Triggered when the user thumbs up on a response.   |
| `trackChatThumbsDown` | `(query: string, response: string)=> void` | Triggered when the user thumbs down on a response. |
| `trackChatFollowup`   | `(query: string)=> void`                   | Triggered when the user asks a question.           |
| `trackChatClose`      | `(queriesCount: number)=> void`            | Triggered when the user exits the chat widget.     |


# Authentication

You can set authentication parameters to let users use their real API keys.

## Enabling Authentication

You can add an authentication method to your mint.json to enable it on every page or you can set it on a per-page basis.

The page's authentication method will override mint.json if both are set.

### Bearer Token

<CodeGroup>
  ```json mint.json
  "api": {
      "auth": {
          "method": "bearer"
      }
  }
  ```

  ```md Page Metadata
  ---
  title: "Your page title"
  authMethod: "bearer"
  ---
  ```
</CodeGroup>

### Basic Authentication

<CodeGroup>
  ```json mint.json
  "api": {
      "auth": {
          "method": "basic"
      }
  }
  ```

  ```md Page Metadata
  ---
  title: "Your page title"
  authMethod: "basic"
  ---
  ```
</CodeGroup>

### API Key

<CodeGroup>
  ```json mint.json
  "api": {
      "auth": {
          "method": "key",
          "name": "x-api-key"
      }
  }
  ```

  ```md Page Metadata
  ---
  title: "Your page title"
  authMethod: "key"
  ---
  ```
</CodeGroup>

### None

The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in mint.json.

<CodeGroup>
  ```md Page Metadata
  ---
  title: "Your page title"
  authMethod: "none"
  ---
  ```
</CodeGroup>


# MDX Setup

Generate docs pages for your API endpoints using MDX

Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.

<Steps>
  <Step title="Configure your API">
    In your `mint.json` file, define your base URL and auth method:

    ```json
    {
      "api": {
        "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
        "auth": {
          "method": "bearer" // 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": {
          "mode": "hide"
        }
      }
    }
    ```

    Find a full list of API configurations [here](/settings/global#api-configurations).
  </Step>

  <Step title="Create your endpoint pages">
    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}
    ```

    <Note>
      If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
    </Note>
  </Step>

  <Step title="Add your endpoints to your docs">
    Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
  </Step>
</Steps>


# 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

<Warning>Mintlify treats the `oneOf` and `anyOf` keywords the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user.</Warning>

<Info>Mintlify currently does not support the `not` keyword.</Info>

### 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
```

<ParamField body="org_with_users" type="object">
  <Expandable>
    <ParamField body="id" type="string">
      The ID of the organization
    </ParamField>

    <ParamField body="users" type="object[]">
      An array containing all users in the organization
    </ParamField>
  </Expandable>
</ParamField>

### 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
        ...
```

<ParamField body="delivery_address" type="object">
  <div className="mt-4 rounded-xl border border-gray-100 px-4 pb-4 pt-2 dark:border-white/10">
    <Tabs>
      <Tab title="StreetAddress">
        <ParamField body="address_line_1" type="string">
          The street address of the residence
        </ParamField>
      </Tab>

      <Tab title="POBox">
        <ParamField body="box_number" type="string">
          The number of the PO Box
        </ParamField>
      </Tab>
    </Tabs>
  </div>
</ParamField>

## `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:

<ParamField body="lang" type="string" required>
  The language of the code sample.
</ParamField>

<ParamField body="label" type="string">
  The label for the sample. This is useful when providing multiple examples for a single endpoint.
</ParamField>

<ParamField body="source" type="string" required>
  The source code of the sample.
</ParamField>

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

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+.

## Autogenerating the API playground

You can either [autogenerate the API playground](/settings/navigation#tabs) or
create MDX files for the individual OpenAPI endpoints.

### Auto-populate API pages

You can add an `openapi` field to an object in the `tabs` or `anchors` array in
the `mint.json`. This can either be with OpenAPI documents that are in the docs
repo (json or yaml) or hosted at a link.

**Example with Anchors:**

```json {5}
{
  "anchors": [
    {
      "name": "API Reference",
      "openapi": "/path/to/openapi.json",
      "url": "api-reference",
      "icon": "square-terminal"
    }
  ]
}
```

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/anchors-autogeneration-anchors.png)

**Example with Tabs:**

```json {6}
{
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference",
      "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
```

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/autogeneration-with-tabs.png)

### Create MDX files for OpenAPI endpoints

You can also create MDX files associated with each OpenAPI endpoint if you would
like to add additional context to specific pages or have more granular control
over the navigation. Here is
[the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2)
from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech).

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/elevenlabs-mdx-autogeneration-example.png)

If you want to autogenerate MDX files for every endpoint in your OpenAPI
document you can use our scraper.

#### Autogenerate files

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. If you're using a publicly-hosted OpenAPI
document, you can supply the URL in place of a path.

```bash
npx @mintlify/scraping@latest openapi-file <path-to-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 <path-to-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.

<Note>
  If your OpenAPI document is invalid, the files will not autogenerate.
</Note>

#### Manually specify files

<Snippet file="api-playground/openapi.mdx" />

By using the OpenAPI reference, the name, description, parameters, responses,
and the API playground will be automatically generated using the specifications.

If you have multiple OpenAPI files, include the path to the OpenAPI file to map
the MDX file to the appropriate OpenAPI file. This is not required if you have
only one OpenAPI file - it will automatically detect your OpenAPI file.

<CodeGroup>
  ```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
  ---
  ```
</CodeGroup>

<br />

<Note>
  The method endpoint must match the endpoint specified in the OpenAPI
  specifications exactly. If the endpoint doesn't exist in the OpenAPI file,
  the page will be empty.
</Note>

## 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:

<CodeGroup>
  ```md Example
  ---
  openapi-schema: OrderItem
  ---
  ```

  ```md Format
  ---
  openapi-schema: "schema-key"
  ---
  ```
</CodeGroup>


# Writing OpenAPI

Use OpenAPI features to enhance your Mintlify docs

## 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

<Note>
  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).
</Note>

## 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.


# Interactive Playground

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.

<Info>
  Autogenerating API pages with OpenAPI will automatically generate API
  playground. Read more about using OpenAPI with Mintlify
  [here](/api-playground/openapi).
</Info>


# 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:

<AccordionGroup>
  <Accordion title="All of my OpenAPI pages are completely blank">
    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):

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/convert-oas-3.png" />
    </Frame>
  </Accordion>

  <Accordion title="One of my OpenAPI pages is completely blank">
    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}"
    ---
    ```
  </Accordion>

  <Accordion title="Requests from the API Playground don't work">
    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 `mint.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.
  </Accordion>
</AccordionGroup>


# Product Updates

New updates and improvements

<Update label="November 2024">
  ## Web Editor

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/webeditor.jpg" alt="Web Editor" />
  </Frame>

  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

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/llms.jpg" alt="llms.txt support" />
  </Frame>

  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.
</Update>

<Update label="October 2024">
  ## Changelogs

  Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users.

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/changelog.jpg" alt="Changelog" />
  </Frame>

  ## 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

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/advanced-footer.gif" alt="Advanced Footer" />
  </Frame>

  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 user auth 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.
</Update>

<Update label="September 2024">
  ## Custom Fonts

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/custom-fonts.jpeg" alt="Custom Fonts" />
  </Frame>

  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

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/performance-improvements.png" alt="Performance Improvements" />
  </Frame>

  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

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/seo-improvements.jpeg" alt="SEO Improvements" />
  </Frame>

  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)
</Update>

<Update label="August 2024">
  ## 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.
</Update>

<Update label="July 2024">
  ## AI Widget

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/changelog/widget.png" alt="AI Widget" />
  </Frame>

  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)
  *   [Learn how to install the Widget](/advanced/widget/chat#getting-started)

  ## 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.
</Update>


# Code Blocks

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

Group multiple accordions into a single display.

Simply add `<AccordionGroup>` around your existing `<Accordion>` components.

<AccordionGroup>
  <Accordion title="FAQ without Icon">
    You can put other components inside Accordions.

    ```java HelloWorld.java
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```
  </Accordion>

  <Accordion title="FAQ with Icon" icon="alien-8bit">
    Check out the [Accordion](/content/components/accordions) docs for all the supported props.
  </Accordion>

  <Accordion title="FAQ without Icon">
    Check out the [Accordion](/content/components/accordions) docs for all the supported props.
  </Accordion>
</AccordionGroup>

<RequestExample>
  ````jsx Accordion Group Example
  <AccordionGroup>
    <Accordion title="FAQ without Icon">
      You can put other components inside Accordions.

      ```java HelloWorld.java
      class HelloWorld {
          public static void main(String[] args) {
              System.out.println("Hello, World!");
          }
      }
      ```

    </Accordion>

    <Accordion title="FAQ with Icon" icon="alien-8bit">
      Check out the [Accordion](/content/components/accordions) docs for all the supported props.
    </Accordion>

    <Accordion title="FAQ without Icon">
      Check out the [Accordion](/content/components/accordions) docs for all the supported props.
    </Accordion>
  </AccordionGroup>
  ````
</RequestExample>

`AccordionGroup` does not have any props.


# Accordions

A dropdown component for toggling content

<Accordion title="I am an Accordion.">
  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.
</Accordion>

<RequestExample>
  ```jsx Accordion Example
  <Accordion title="I am an Accordion.">
    You can put any content in here.
  </Accordion>
  ```
</RequestExample>

## Props

<ResponseField name="title" type="string" required>
  Title in the Accordion preview.
</ResponseField>

<ResponseField name="description" type="string">
  Detail below the title in the Accordion preview.
</ResponseField>

<ResponseField name="defaultOpen" type="boolean" default="false">
  Whether the Accordion is open by default.
</ResponseField>

<ResponseField name="icon" type="string or svg">
  A [Font Awesome icon](https://fontawesome.com/icons) or SVG code
</ResponseField>

<ResponseField name="iconType" type="string">
  One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or
  "brands"
</ResponseField>


# Callout Boxes

Use callouts to add eye-catching context to your content

### Note Callouts

<Note>This adds a note in the content</Note>

```jsx
<Note>This adds a note in the content</Note>
```

### Warning Callouts

<Warning>This raises a warning to watch out for</Warning>

```jsx
<Warning>This raises a warning to watch out for</Warning>
```

### Info Callouts

<Info>This draws attention to important information</Info>

```jsx
<Info>This draws attention to important information</Info>
```

### Tip Callouts

<Tip>This suggests a helpful tip</Tip>

```jsx
<Tip>This suggests a helpful tip</Tip>
```

### Check Callouts

<Check>This brings us a checked status</Check>

```jsx
<Check>This brings us a checked status</Check>
```


# 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.

<CardGroup cols={2}>
  <Card title="First Card" icon="square-1">
    Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
  </Card>

  <Card title="Second Card" icon="square-2">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit
  </Card>

  <Card title="Third Card" icon="square-3">
    Ut enim ad minim veniam, quis nostrud exercitation ullamco
  </Card>

  <Card title="Fourth Card" icon="square-4">
    Excepteur sint occaecat cupidatat non proident
  </Card>
</CardGroup>

<RequestExample>
  ```jsx Card Group Example
  <CardGroup cols={2}>
    <Card title="First Card" icon="square-1">
      Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
    </Card>
    <Card title="Second Card" icon="square-2">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit
    </Card>
    <Card title="Third Card" icon="square-3">
      Ut enim ad minim veniam, quis nostrud exercitation ullamco
    </Card>
    <Card title="Fourth Card" icon="square-4">
      Excepteur sint occaecat cupidatat non proident
    </Card>
  </CardGroup>
  ```
</RequestExample>

## Props

<ResponseField name="cols" default={2}>
  The number of columns per row
</ResponseField>


# Cards

Highlight main points or links with customizable icons

<Card title="Card Title" icon="link" href="/content/components/card-groups">
  This is how you use a card with an icon and a link. Clicking on this card
  brings you to the Card Group page.
</Card>

<RequestExample>
  ```jsx Card Example
  <Card title="Click on me" icon="link" href="/content/components/card-group">
    This is how you use a card with an icon and a link. Clicking on this card
    brings you to the Card Group page.
  </Card>
  ```

  ```jsx Image Card Example
  <Card title="Image Card" img="/images/card-with-image.png">
    Here is an example of a card with an image
  </Card>
  ```
</RequestExample>

### Horizontal Card

Add a `horizontal` property to a card to make it horizontally displayed.

<Card title="Horizontal Card" icon="text-size" horizontal>
  Here is an example of a horizontal card
</Card>

### Image Card

Add an `img` property to a card to display an image on the top of the card.

<Card title="Image Card" img="https://mintlify-assets.b-cdn.net/yosemite.jpg">
  Here is an example of a card with an image
</Card>

## Props

<ResponseField name="title" type="string" required>
  The title of the card
</ResponseField>

<ResponseField name="icon" type="string or svg">
  A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}`
</ResponseField>

<ResponseField name="iconType" type="string">
  One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
</ResponseField>

<ResponseField name="color" type="string">
  The color of the icon as a hex code
</ResponseField>

<ResponseField name="href" type="string">
  The url that clicking on the card would navigate the user to
</ResponseField>

<ResponseField name="horizontal" type="boolean">
  Makes the card more compact and horizontal
</ResponseField>

<ResponseField name="img" type="string">
  The url or local path to an image to display on the top of the card
</ResponseField>


# Code Blocks

Display code with optional syntax highlighting

<RequestExample>
  ````md Code Block Example
  ```javascript Code Block Example
  const hello = "world";
  ```
  ````
</RequestExample>

## 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

You can add more text 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

You can 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();
```
````

## Code Groups

Want to display multiple code examples in one code box? Check out the Code Group docs:

<Card title="Code Group" href="/content/components/code-groups" icon="columns-3">
  Read the reference for the Code Group component
</Card>


# 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 `<CodeGroup>` 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.

<CodeGroup>
  ```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!");
      }
  }
  ```
</CodeGroup>

<RequestExample>
  ````md Code Group Example
  <CodeGroup>

  ```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!");
      }
  }
  ```

  </CodeGroup>
  ````
</RequestExample>


# Expandables

Toggle to display nested properties.

<ResponseField name="user" type="User Object">
  <Expandable title="properties">
    <ResponseField name="full_name" type="string">
      The full name of the user
    </ResponseField>

    <ResponseField name="is_over_21" type="boolean">
      Whether the user is over 21 years old
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```jsx Expandable Example
  <ResponseField name="user" type="User Object">
    <Expandable title="properties">
      <ResponseField name="full_name" type="string">
        The full name of the user
      </ResponseField>

      <ResponseField name="is_over_21" type="boolean">
        Whether the user is over 21 years old
      </ResponseField>
    </Expandable>
  </ResponseField>
  ```
</RequestExample>

## Props

<ResponseField name="title" type="string">
  The name of the object you are showing. Used to generate the "Show NAME" and
  "Hide NAME" text.
</ResponseField>

<ResponseField name="defaultOpen" type="boolean" default="false">
  Set to true to show the component as open when the page loads.
</ResponseField>


# 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.

<Frame>
  <img src="https://mintlify-assets.b-cdn.net/yellowstone.jpeg" />
</Frame>

## Captions

You can add additional context to an image using the optional `caption` prop.

<Frame caption="Yosemite National Park is visited by over 3.5 million people every year">
  <img src="https://mintlify-assets.b-cdn.net/yosemite.jpg" />
</Frame>

## Props

<ResponseField name="caption" type="string">
  Optional caption text to show centered under your component.
</ResponseField>

<RequestExample>
  ```jsx Frame
  <Frame>
    <img src="/path/image.jpg" />
  </Frame>
  ```

  ```jsx Frame with Captions
  <Frame caption="Caption Text">
    <img src="/path/image.jpg" />
  </Frame>
  ```
</RequestExample>


# Icons

Use [Font Awesome](https://fontawesome.com/icons) icons anywhere in the doc

<Icon icon="check" size={32} />

<RequestExample>
  ```jsx Icon Example
  <Icon icon="check" size={32} />
  ```
</RequestExample>

## Inline Icons

The icon will be placed inline when used in a paragraph.

```markdown Inline Icon Example
<Icon icon="check" iconType="solid" /> The documentation you want, effortlessly 
```

<Icon icon="check" iconType="solid" /> The documentation you want, effortlessly

## Props

<ResponseField name="icon" type="string" required>
  A [Font Awesome](https://fontawesome.com/icons) icon
</ResponseField>

<ResponseField name="iconType" type="string">
  One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
</ResponseField>

<ResponseField name="color" type="string">
  The color of the icon as a hex code (e.g., `#FF5733`)
</ResponseField>

<ResponseField name="size" type="number">
  The size of the icon in pixels
</ResponseField>


# Mermaid Diagrams

Display diagrams using Mermaid

<RequestExample>
  ````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
  ```
  ````
</RequestExample>

[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

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).

<ParamField path="param" type="string" required>
  An example of a parameter field
</ParamField>

<RequestExample>
  ```jsx Path Example
  <ParamField path="param" type="string">
    An example of a parameter field
  </ParamField>
  ```

  ```jsx Query Example
  <ParamField query="filter" type="string" default="none" required>
    The filtering command used to sort through the users
  </ParamField>
  ```

  ```jsx Body Example
  <ParamField body="user_age" type="integer" default="0" required>
    The age of the user. Cannot be less than 0
  </ParamField>
  ```
</RequestExample>

## Props

<ParamField body="query, path, body, or header" type="string">
  Whether it is a query, path, body, or header parameter followed by the name
</ParamField>

<ParamField body="type" type="string">
  Expected type of the parameter's value
</ParamField>

<ParamField body="required" type="boolean">
  Indicate whether the parameter is required
</ParamField>

<ParamField body="deprecated" type="boolean">
  Indicate whether the parameter is deprecated
</ParamField>

<ParamField body="default" type="string">
  Default value used by the server if the request does not provide a value
</ParamField>

<ParamField body="initialValue" type="any">
  Value that will be used to initialize the playground
</ParamField>

<ParamField body="placeholder" type="string">
  Placeholder text for the input in the playground
</ParamField>

<ParamField body="children" type="string">
  Description of the parameter (markdown enabled)
</ParamField>


# Response Fields

Display API response values

The `<ResponseField>` component is designed to define the return values of an API. Many docs also use `<ResponseField>` on pages when you need to list the types of something.

<ResponseField name="response" type="string" required>
  A response field example
</ResponseField>

<RequestExample>
  ```jsx ResponseField Example
  <ResponseField name="response" type="string" required>
    A response field example
  </ResponseField>
  ```
</RequestExample>

## Props

<ResponseField name="name" type="string" required>
  The name of the response value.
</ResponseField>

<ResponseField name="type" type="string" required>
  Expected type of the response value
</ResponseField>

<ResponseField name="default" type="string">
  The default value.
</ResponseField>

<ResponseField name="required" type="boolean">
  Show "required" beside the field name.
</ResponseField>


# 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.

<Steps>
  <Step title="First Step">
    These are instructions or content that only pertain to the first step.
  </Step>

  <Step title="Second Step">
    These are instructions or content that only pertain to the second step.
  </Step>

  <Step title="Third Step">
    These are instructions or content that only pertain to the third step.
  </Step>
</Steps>

<RequestExample>
  ```jsx Steps Example
  <Steps>
    <Step title="First Step">
      These are instructions or content that only pertain to the first step.
    </Step>
    <Step title="Second Step">
      These are instructions or content that only pertain to the second step.
    </Step>
    <Step title="Third Step">
      These are instructions or content that only pertain to the third step.
    </Step>
  </Steps>
  ```
</RequestExample>

## Steps Props

<ResponseField name="children" type="ReactElement<StepProps>[]" required>
  A list of `Step` components.
</ResponseField>

<ResponseField name="titleSize" type="string" default="p">
  The size of the step titles. One of `p`, `h2` and `h3`.
</ResponseField>

## Individual Step Props

<ResponseField name="children" type="string | ReactNode" required>
  The content of a step either as plain text, or components.
</ResponseField>

<ResponseField name="icon" type="string or svg">
  A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}`
</ResponseField>

<ResponseField name="iconType" type="string">
  One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
</ResponseField>

<ResponseField name="title" type="string">
  The title is the primary text for the step and shows up next to the indicator.
</ResponseField>

<ResponseField name="stepNumber" type="number">
  The number of the step.
</ResponseField>

<ResponseField name="titleSize" type="string" default="p">
  The size of the step titles. One of `p`, `h2` and `h3`.
</ResponseField>


# Sidebar Code Examples

Display code blocks at the top-right of the page on desktop devices

The `<RequestExample>` and `<ResponseExample>` 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.

`<RequestExample>` and `<ResponseExample>` show up like regular code blocks on mobile.

## Request Example

The `<RequestExample>` 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 `<RequestExample>`.

Please set a name on every code block you put inside RequestExample.

<RequestExample>
  ````md RequestExample Example
  <RequestExample>

  ```bash Request
    curl --request POST \
      --url https://dog-api.kinduff.com/api/facts
  ```

  </RequestExample>
  ````
</RequestExample>

## Response Example

The `<ResponseExample>` component is the same as `<RequestExample>` but will show up underneath it.

<ResponseExample>
  ````md ResponseExample Example
  <ResponseExample>

  ```json Response
  { "status": "success" }
  ```

  </ResponseExample>
  ````
</ResponseExample>


# Tabs

Toggle content using the Tabs component

You can add any number of tabs.

<Tabs>
  <Tab title="First Tab">
    ☝️ Welcome to the content that you can only see inside the first Tab.
  </Tab>

  <Tab title="Second Tab">
    ✌️ Here's content that's only inside the second Tab.
  </Tab>

  <Tab title="Third Tab">
    💪 Here's content that's only inside the third Tab.
  </Tab>
</Tabs>

<RequestExample>
  ```jsx Tabs Example
  <Tabs>
    <Tab title="First Tab">
      ☝️ Welcome to the content that you can only see inside the first Tab.
    </Tab>
    <Tab title="Second Tab">
      ✌️ Here's content that's only inside the second Tab.
    </Tab>
    <Tab title="Third Tab">
      💪 Here's content that's only inside the third Tab.
    </Tab>
  </Tabs>
  ```
</RequestExample>

## Tab Props

<ResponseField name="title" type="string" required>
  The title of the tab. Short titles are easier to navigate.
</ResponseField>


# Tooltips

Show a definition when you hover over text.

<Tooltip tip="This is a tooltip!">Hover over me</Tooltip> and see a tooltip in action

<RequestExample>
  ```jsx Tooltip Example
  <Tooltip tip="This is a tooltip!">Hover over me</Tooltip>
  ```
</RequestExample>


# Update

Keep track of changes and updates

The `Update` component is used to keep track of changes and updates.

<Update label="2024-10-12" description="v0.1.1">
  <Frame>
    <img className="block" src="https://mintlify-assets.b-cdn.net/hero-light.png" />
  </Frame>

  ## 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
</Update>

<Update label="2024-10-11" description="v0.1.0">
  ### How to use

  ```md
  <Update label="2024-10-12" description="v0.1.1">
    This is how you use a changelog with a label 
    and a description.
  </Update>
  <Update label="2024-10-11" description="v0.1.0">
    This is how you use a changelog with a label 
    and a description.
  </Update>
  ```

  You can use multiple `Update` components to create changelogs.
</Update>

<Tip>
  Each `label` creates an anchor and also shows up on the table of contents on the right.
</Tip>

## Props

<ResponseField name="label" type="string" required>
  Label in the changelog, on the sticky left side.
</ResponseField>

<ResponseField name="description" type="string">
  Description below the label in the Changelog preview.
</ResponseField>


# Local Development

Preview changes locally to update your docs

<Info>
  **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
</Info>

**Step 1**: Install Mintlify:

<CodeGroup>
  ```bash npm
  npm i -g mintlify
  ```

  ```bash yarn
  yarn global add mintlify
  ```
</CodeGroup>

**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:

```bash
mintlify dev
```

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 Mintlify runs on by 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 Mintlify 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.
```

## Mintlify 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:

<CodeGroup>
  ```bash npm
  npm i -g mintlify@latest
  ```

  ```bash yarn
  yarn global upgrade mintlify
  ```
</CodeGroup>

## 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:

<Frame>
  <img className="rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png" />
</Frame>

## 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

<AccordionGroup>
  <Accordion title="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
    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`
  </Accordion>

  <Accordion title="Issue: Encountering an unknown error">
    Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
  </Accordion>
</AccordionGroup>


# Images, Videos, and Embeds

Add image, video, and other HTML elements

<img className="rounded-md" src="https://mintlify-assets.b-cdn.net/bigbend.jpg" />

<Info>
  Mintlify supports files up to 5 MB. To use larger files, consider a storage
  service like Cloudinary and embed in your Mintlify documentation.
</Info>

## Image

### Using Markdown

The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code

```md
![title](/path/image.jpg)
```

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
<img height="200" src="/path/image.jpg" />
```

### Disable Image Zoom

To disable the default zoom on click for images, add the noZoom property to image embeds.

```html
<img height="200" noZoom src="/path/image.jpg" />
```

### 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
<a href="https://mintlify.com" target="_blank">
  <img height="200" noZoom src="/path/image.jpg" />
</a>
```

### Dark Mode

To use separate images for light and dark mode, use Tailwind CSS to hide and show images.

```html
<img className="block h-32 dark:hidden" src="/path/image-light.jpg" />
<img className="hidden h-32 dark:block" src="/path/image-dark.jpg" />
```

### Related

For more information, we recommend the following sections:

<Card title="Frame Component Reference" icon="frame" href="/content/components/frames">
  Read the reference for the Frame component
</Card>

## Videos

<iframe className="w-full aspect-video rounded-md" src="https://www.youtube.com/embed/4KzFe50RQkQ" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

<br />

<Tip>
  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.
</Tip>

For YouTube videos use:

```html
<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>
```

For other videos, use:

```html
<video
  controls
  className="w-full aspect-video"
  src="link-to-your-video.com"
></video>
```

To autoplay the video, use:

```html
<video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video"
  src="link-to-your-video.com"
></video>
```

<Warning>
  Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to
  be written in camelCase: autoPlay, playsInline.
</Warning>

## iFrames

Loads another HTML page within the document.

```html
<iframe src="https://www.youtube.com/embed/4KzFe50RQkQ"> </iframe>
```

<Tip>
  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/).
</Tip>


# Amplitude



Add the following to your `mint.json` file to send analytics to Amplitude.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "amplitude": {
          "apiKey": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "amplitude": {
          "apiKey": "76bb138bf3fbf58186XXX00000"
      }
  }
  ```
</CodeGroup>


# Clearbit



Add the following to your `mint.json` file to send analytics to Clearbit.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "clearbit": {
          "publicApiKey": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "clearbit": {
          "publicApiKey": "pk_1a1882"
      }
  }
  ```
</CodeGroup>


# Fathom



Add the following to your `mint.json` file to send analytics to Fathom.

You can get the `siteId` from your script settings.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "fathom": {
          "siteId": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "fathom": {
          "siteId": "YSVMSDAY"
      }
  }
  ```
</CodeGroup>


# Google Analytics 4



You will need to generate a new <Tooltip tip="Google Analytics 4">GA4</Tooltip> 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 <Tooltip tip="Google Analytics 4">GA4</Tooltip> property. <Tooltip tip="Google Analytics 4">GA4</Tooltip> 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.

<Frame>![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/ga4-web-streams.png)</Frame>

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 mint.json

Add your Measurement ID to your `mint.json` file like so:

```json mint.json
"analytics": {
    "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.

<Note>
  Preview links have analytics turned off.
</Note>


# Google Tag Manager



Add your tag ID to `mint.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.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "gtm": {
          "tagId": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "gtm": {
          "tagId": "GTM-MGBL4PW"
      }
  }
  ```
</CodeGroup>


# Heap



Add the following to your `mint.json` file to send analytics to Heap.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "heap": {
          "appId": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "heap": {
          "appId": "1234567890"
      }
  }
  ```
</CodeGroup>


# HotJar



Add the following to your `mint.json` file to send analytics to HotJar.

```json Analytics options in mint.json
"analytics": {
    "hotjar": {
        "hjid": "required",
        "hjsv": "required"
    }
}
```


# Koala



Add the following to your `mint.json` file to send analytics to Koala.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "koala": {
          "publicApiKey": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "koala": {
          "publicApiKey": "pk_1a1882"
      }
  }
  ```
</CodeGroup>


# LogRocket



Add the following to your `mint.json` file to send analytics to LogRocket.

```json Analytics options in mint.json
"analytics": {
    "logrocket": {
        "apiKey": "required"
    }
}
```


# Mixpanel



Add the following to your `mint.json` file to send analytics to Mixpanel.

```json Analytics options in mint.json
"analytics": {
    "mixpanel": {
        "projectToken": "required"
    }
}
```


# Analytics Integrations

Integrate with an analytics platform to track viewer events

<CardGroup cols={2}>
  <Card
    title="Amplitude"
    href="/integrations/analytics/amplitude"
    horizontal
    icon={<svg className="h-6 w-6" width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path d="M15.5988 8.04494C15.4989 7.91714 15.3924 7.84668 15.2646 7.84668C15.1728 7.85323 15.0876 7.88273 15.009 7.93188C14.0635 8.67087 12.7773 11.8055 11.7188 15.9412L12.6576 15.9477C14.5059 15.969 16.4165 15.9903 18.3008 16.0182C17.8027 14.1273 17.3341 12.5068 16.9015 11.1926C16.2674 9.28205 15.8414 8.42181 15.5988 8.04494Z" fill="#1E61F0"/>
     <path d="M17.6964 0.078125C7.92405 0.078125 0 8.00217 0 17.7745C0 27.5468 7.92405 35.4709 17.6964 35.4709C27.4687 35.4709 35.3928 27.5468 35.3928 17.7745C35.3928 8.00217 27.4687 0.078125 17.6964 0.078125ZM30.7589 17.5615C30.7098 17.7598 30.5885 17.9531 30.4181 18.094C30.3968 18.1088 30.3755 18.1219 30.3542 18.1366L30.3329 18.1514L30.2903 18.1792L30.2543 18.2005C30.1199 18.271 29.9692 18.307 29.8135 18.307H21.4274C21.4913 18.584 21.5699 18.9035 21.6469 19.2459C22.109 21.2286 23.3248 26.5014 24.6242 26.5014H24.652H24.6668H24.6946C25.704 26.5014 26.2234 25.0382 27.3606 21.8316L27.3753 21.7955C27.5605 21.2843 27.7669 20.701 27.9865 20.0832L28.0439 19.9276C28.1291 19.7211 28.3634 19.6146 28.5698 19.6998C28.7189 19.7572 28.8254 19.9063 28.8254 20.0701C28.8254 20.1127 28.8189 20.1488 28.8107 20.1832L28.7615 20.3388C28.6403 20.7223 28.5207 21.2417 28.3699 21.8463C27.6948 24.6466 26.6707 28.8757 24.0556 28.8757H24.0343C22.3433 28.861 21.334 26.1606 20.8998 25.0022C20.0903 22.8409 19.4791 20.5453 18.8893 18.3152H11.1864L9.58718 23.439L9.56588 23.4177C9.32501 23.7946 8.82034 23.9076 8.44347 23.6668C8.20916 23.5176 8.0666 23.262 8.0666 22.9851V22.9573L8.16655 22.3739C8.38612 21.0598 8.65648 19.6867 8.9547 18.3087H5.68578L5.67104 18.2939C5.00251 18.194 4.54043 17.5697 4.64039 16.9012C4.71904 16.3817 5.1172 15.9705 5.62843 15.8771C5.75624 15.8623 5.88405 15.8558 6.01186 15.8623H6.16752C7.19817 15.8771 8.29272 15.8984 9.50034 15.9115C11.1995 9.00333 13.1674 5.49191 15.3565 5.48535C17.7013 5.48535 19.4431 10.8221 20.8359 16.0458L20.8424 16.0671C23.7 16.1245 26.756 16.2097 29.7185 16.4227L29.8463 16.4374C29.8954 16.4374 29.938 16.444 29.9888 16.4522H30.0036L30.0183 16.4588H30.0249C30.5312 16.5587 30.8654 17.0568 30.7589 17.5615Z" fill="#1E61F0"/>
    </svg>}
  />

  <Card
    title="Mixpanel"
    href="/integrations/analytics/mixpanel"
    horizontal
    icon={
     <svg
       className="h-6 w-6"
       style={{ fill: "#7856ff" }}
       viewBox="0 0 98 98"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path d="M24.2391 58.7912C29.877 58.7912 34.4475 54.2207 34.4475 48.5828C34.4475 42.9449 29.877 38.3745 24.2391 38.3745C18.6012 38.3745 14.0308 42.9449 14.0308 48.5828C14.0308 54.2207 18.6012 58.7912 24.2391 58.7912Z"></path>
       <path d="M54.7787 55.7046C58.7675 55.7046 62.0011 52.4716 62.0011 48.4834C62.0011 44.4952 58.7675 41.2622 54.7787 41.2622C50.7899 41.2622 47.5563 44.4952 47.5563 48.4834C47.5563 52.4716 50.7899 55.7046 54.7787 55.7046Z"></path>
       <path d="M78.6018 52.0652C80.547 52.0652 82.1239 50.4883 82.1239 48.5431C82.1239 46.5979 80.547 45.021 78.6018 45.021C76.6566 45.021 75.0798 46.5979 75.0798 48.5431C75.0798 50.4883 76.6566 52.0652 78.6018 52.0652Z"></path>
     </svg>
    }
  />

  <Card
    title="PostHog"
    href="/integrations/analytics/posthog"
    horizontal
    icon={
     <svg
       className="h-6 w-6"
       width="50"
       height="30"
       viewBox="0 0 50 30"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path
         d="M10.8914 17.2057c-.3685.7371-1.42031.7371-1.78884 0L8.2212 15.443c-.14077-.2815-.14077-.6129 0-.8944l.88136-1.7627c.36853-.7371 1.42034-.7371 1.78884 0l.8814 1.7627c.1407.2815.1407.6129 0 .8944l-.8814 1.7627zM10.8914 27.2028c-.3685.737-1.42031.737-1.78884 0L8.2212 25.44c-.14077-.2815-.14077-.6129 0-.8944l.88136-1.7627c.36853-.7371 1.42034-.7371 1.78884 0l.8814 1.7627c.1407.2815.1407.6129 0 .8944l-.8814 1.7628z"
         fill="#1D4AFF"
       />
       <path
         d="M0 23.4082c0-.8909 1.07714-1.3371 1.70711-.7071l4.58338 4.5834c.62997.63.1838 1.7071-.7071 1.7071H.999999c-.552284 0-.999999-.4477-.999999-1v-4.5834zm0-4.8278c0 .2652.105357.5196.292893.7071l9.411217 9.4112c.18753.1875.44189.2929.70709.2929h5.1692c.8909 0 1.3371-1.0771.7071-1.7071L1.70711 12.7041C1.07714 12.0741 0 12.5203 0 13.4112v5.1692zm0-9.99701c0 .26521.105357.51957.292893.7071L19.7011 28.6987c.1875.1875.4419.2929.7071.2929h5.1692c.8909 0 1.3371-1.0771.7071-1.7071L1.70711 2.70711C1.07715 2.07715 0 2.52331 0 3.41421v5.16918zm9.997 0c0 .26521.1054.51957.2929.7071l17.994 17.99401c.63.63 1.7071.1838 1.7071-.7071v-5.1692c0-.2652-.1054-.5196-.2929-.7071l-17.994-17.994c-.63-.62996-1.7071-.18379-1.7071.70711v5.16918zm11.7041-5.87628c-.63-.62997-1.7071-.1838-1.7071.7071v5.16918c0 .26521.1054.51957.2929.7071l7.997 7.99701c.63.63 1.7071.1838 1.7071-.7071v-5.1692c0-.2652-.1054-.5196-.2929-.7071l-7.997-7.99699z"
         fill="#F9BD2B"
       />
       <path
         d="M42.5248 23.5308l-9.4127-9.4127c-.63-.63-1.7071-.1838-1.7071.7071v13.1664c0 .5523.4477 1 1 1h14.5806c.5523 0 1-.4477 1-1v-1.199c0-.5523-.4496-.9934-.9973-1.0647-1.6807-.2188-3.2528-.9864-4.4635-2.1971zm-6.3213 2.2618c-.8829 0-1.5995-.7166-1.5995-1.5996 0-.8829.7166-1.5995 1.5995-1.5995.883 0 1.5996.7166 1.5996 1.5995 0 .883-.7166 1.5996-1.5996 1.5996z"
         fill="#000"
       />
       <path
         d="M0 27.9916c0 .5523.447715 1 1 1h4.58339c.8909 0 1.33707-1.0771.70711-1.7071l-4.58339-4.5834C1.07714 22.0711 0 22.5173 0 23.4082v4.5834zM9.997 10.997L1.70711 2.70711C1.07714 2.07714 0 2.52331 0 3.41421v5.16918c0 .26521.105357.51957.292893.7071L9.997 18.9946V10.997zM1.70711 12.7041C1.07714 12.0741 0 12.5203 0 13.4112v5.1692c0 .2652.105357.5196.292893.7071L9.997 28.9916V20.994l-8.28989-8.2899z"
         fill="#1D4AFF"
       />
       <path
         d="M19.994 11.4112c0-.2652-.1053-.5196-.2929-.7071l-7.997-7.99699c-.6299-.62997-1.70709-.1838-1.70709.7071v5.16918c0 .26521.10539.51957.29289.7071l9.7041 9.70411v-7.5834zM9.99701 28.9916h5.58339c.8909 0 1.3371-1.0771.7071-1.7071L9.99701 20.994v7.9976zM9.99701 10.997v7.5834c0 .2652.10539.5196.29289.7071l9.7041 9.7041v-7.5834c0-.2652-.1053-.5196-.2929-.7071L9.99701 10.997z"
         fill="#F54E00"
       />
     </svg>
    }
  />

  <Card
    title="Google Analytics 4 (GA4)"
    href="/integrations/analytics/google-analytics"
    horizontal
    icon={
     <svg
       className="h-6 w-6"
       xmlns="http://www.w3.org/2000/svg"
       width="64"
       height="64"
       viewBox="0 0 64 64"
     >
       <g transform="matrix(.363638 0 0 .363636 -3.272763 -2.909091)">
         <path
           d="M130 29v132c0 14.77 10.2 23 21 23 10 0 21-7 21-23V30c0-13.54-10-22-21-22s-21 9.33-21 21z"
           fill="#f9ab00"
         />
         <g fill="#e37400">
           <path d="M75 96v65c0 14.77 10.2 23 21 23 10 0 21-7 21-23V97c0-13.54-10-22-21-22s-21 9.33-21 21z" />
           <circle cx="41" cy="163" r="21" />
         </g>
       </g>
     </svg>
    }
  />

  <Card
    title="Google Tag Manager"
    href="/integrations/analytics/google-tag-manager"
    horizontal
    icon={
     <svg
       className="h-6 w-6"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       x="0px"
       y="0px"
       width="192px"
       height="192px"
       viewBox="0 0 192 192"
       enableBackground="new 0 0 192 192"
     >
       <rect fill="none" width="192" height="192" />
       <g>
         <polygon
           fill="#8AB4F8"
           points="111.31,176.79 80.76,147 146.37,80 178,111 	"
         />
         <path
           fill="#4285F4"
           d="M111.44,45.08L81,14L14.44,79.93c-8.58,8.58-8.58,22.49,0,31.08L80,177l31-29L61.05,95.47L111.44,45.08z"
         />
         <path
           fill="#8AB4F8"
           d="M177.56,80.44l-66-66c-8.59-8.59-22.52-8.59-31.11,0c-8.59,8.59-8.59,22.52,0,31.11l66,66
     	c8.59,8.59,22.52,8.59,31.11,0C186.15,102.96,186.15,89.03,177.56,80.44z"
         />
         <circle fill="#246FDB" cx="95.5" cy="162.5" r="21.5" />
       </g>
     </svg>
    }
  />

  <Card
    title="HotJar"
    href="/integrations/analytics/hotjar"
    horizontal
    icon={
     <svg
       className="h-6 w-6"
       width="51"
       height="57"
       viewBox="0 0 51 57"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path
         d="M20.9743 23.3016C27.5805 19.6488 36.6281 14.645 36.6281 0.0820312H25.6725C25.6725 8.23006 21.687 10.4338 15.6538 13.7698C9.0477 17.4239 0 22.4256 0 36.99H10.9556C10.9556 28.8414 14.9412 26.6376 20.9743 23.3016Z"
         fill="#FF3C00"
       />
       <path
         d="M39.9362 19.9551C39.9362 28.1035 35.9506 30.3073 29.9175 33.6428C23.3131 37.2956 14.2637 42.2987 14.2637 56.8628H25.2189C25.2189 48.7143 29.2044 46.5106 35.2375 43.1746C41.8436 39.5218 50.8909 34.5193 50.8909 19.9551H39.9362Z"
         fill="#FF3C00"
       />
     </svg>
    }
  />

  <Card
    title="Koala"
    href="/integrations/analytics/koala"
    horizontal
    icon={
     <svg className="h-6 w-6" width="121" height="121" viewBox="0 0 121 121" fill="none" xmlns="http://www.w3.org/2000/svg">
       <path d="M72.5246 72.3223C71.4431 72.3248 70.3866 72.6473 69.4886 73.2503C68.5911 73.8528 67.8916 74.7078 67.4796 75.7078C67.0676 76.7073 66.9611 77.8068 67.1736 78.8673C67.3861 79.9273 67.9081 80.9008 68.6736 81.6648C69.4391 82.4283 70.4136 82.9483 71.4746 83.1583C72.5351 83.3683 73.6346 83.2593 74.6331 82.8448C75.6321 82.4303 76.4856 81.7293 77.0861 80.8303C77.6866 79.9308 78.0071 78.8738 78.0071 77.7923C78.0071 77.0728 77.8651 76.3603 77.5896 75.6958C77.3141 75.0313 76.9101 74.4278 76.4006 73.9198C75.8911 73.4118 75.2866 73.0088 74.6216 72.7348C73.9566 72.4608 73.2436 72.3203 72.5246 72.3223Z" fill="#4D32E4"/>
       <path d="M60.5 0C44.4544 0 29.066 6.3741 17.7201 17.7201C6.3741 29.066 0 44.4544 0 60.5C0 76.5455 6.3741 91.934 17.7201 103.28C29.066 114.626 44.4544 121 60.5 121C76.5455 121 91.934 114.626 103.28 103.28C114.626 91.934 121 76.5455 121 60.5C121 44.4544 114.626 29.066 103.28 17.7201C91.934 6.3741 76.5455 0 60.5 0ZM108.522 84.07C107.203 81.71 105.138 79.855 102.65 78.796C100.163 77.737 97.3945 77.534 94.779 78.2195C92.164 78.9045 89.8505 80.439 88.202 82.5815C86.553 84.724 85.663 87.3535 85.6705 90.057V107.211C85.6705 107.387 85.6705 107.551 85.6705 107.728C78.4335 111.61 70.3975 113.767 62.189 114.03C53.4065 104.206 48.8746 91.3035 49.5848 78.146C50.1465 69.442 53.0275 61.047 57.929 53.8325C58.004 53.7305 58.038 53.6035 58.024 53.4775C58.01 53.351 57.949 53.235 57.853 53.152C57.752 53.089 57.633 53.061 57.515 53.0725C57.3965 53.0835 57.285 53.134 57.1975 53.215C49.6673 59.3625 44.6827 68.0835 43.2071 77.692C43.0432 78.549 42.8541 80.0115 42.7533 80.818C42.7533 81.171 42.2492 81.259 42.0349 81.196C37.9451 79.838 34.2333 77.534 31.201 74.472C28.1687 71.4095 25.9014 67.6755 24.5833 63.5725C23.2651 59.4695 22.9333 55.1135 23.6147 50.8585C24.2962 46.603 25.9717 42.5685 28.5052 39.0824C31.0387 35.5963 34.3587 32.7568 38.1956 30.7947C42.0325 28.8326 46.2781 27.8031 50.5875 27.7899C54.897 27.7767 59.149 28.7802 62.9975 30.7187C66.8465 32.6573 70.184 35.4763 72.7385 38.9469C73 39.3158 73.3455 39.6171 73.7465 39.8254C74.148 40.0337 74.593 40.1429 75.045 40.1442H85.62H109.946C112.846 47.1544 114.22 54.702 113.977 62.2845C113.733 69.867 111.879 77.3105 108.535 84.12L108.522 84.07Z" fill="#4D32E4"/>
     </svg>
    }
  />

  <Card
    title="LogRocket"
    href="/integrations/analytics/logrocket"
    horizontal
    icon={
     <svg
       className="h-7 w-5"
       width="102"
       height="159"
       viewBox="0 0 102 159"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path
         d="M33.7001 18.4998C38.1001 11.4998 44.0001 5.3998 50.9001 0.799805C57.7001 5.2998 63.5001 11.2998 67.9001 18.1998C79.4001 34.1998 85.2001 53.4998 84.4001 73.1998C88.0001 76.0998 91.7001 78.8998 95.2001 81.7998C100.2 86.2998 102.6 93.0998 101.4 99.6998C99.7001 107.9 98.1001 116.1 96.3001 124.3C95.1001 127.9 91.2001 129.8 87.7001 128.6C87.1001 128.4 86.5001 128.1 86.0001 127.7C80.2001 123.1 74.6001 118.3 68.8001 113.6C58.9001 123 43.5001 123.1 33.5001 113.8C29.4001 116.8 25.5001 120.5 21.5001 123.8C19.7001 125.5 17.8001 127.1 15.6001 128.3C12.1001 129.7 8.10011 127.9 6.80011 124.4C6.70011 124.2 6.7001 124 6.6001 123.9C4.8001 115.9 2.8001 107.9 1.0001 99.8998C-0.399898 92.8998 2.1001 85.7998 7.5001 81.1998C10.6001 78.6998 13.8001 76.1998 17.0001 73.6998C17.9001 73.1998 17.4001 72.1998 17.5001 71.4998C17.1001 52.5998 22.8001 33.9998 33.7001 18.4998ZM39.4001 43.2998C35.2001 48.6998 35.7001 56.3998 40.6001 61.1998C46.2001 66.5998 55.1001 66.7998 60.9001 61.5998C65.0001 57.8998 66.4001 51.9998 64.5001 46.7998C62.5001 41.7998 57.9001 38.2998 52.5001 37.8998C47.4001 37.2998 42.5001 39.3998 39.4001 43.2998Z"
         fill="#764ABC"
       />
       <path
         d="M31.7002 130.6C31.8002 128.7 33.5002 127.3 35.3002 127.5C35.8002 127.5 36.3002 127.7 36.7002 127.9C45.6002 132.2 56.0002 132.2 65.0002 127.9C66.7002 127 68.7002 127.7 69.6002 129.3C69.8002 129.6 69.9002 130 70.0002 130.4C70.0002 135.4 70.0002 140.4 70.0002 145.4C69.8002 147.2 68.1002 148.6 66.3002 148.4C65.7002 148.3 65.2002 148.1 64.7002 147.8C63.2002 146.5 61.9002 145.1 60.4002 143.8C58.1002 148.1 56.0002 152.4 53.7002 156.7C52.7002 158.3 50.6002 158.7 49.0002 157.7C48.6002 157.5 48.3002 157.1 48.1002 156.8C45.8002 152.5 43.7002 148.2 41.3002 143.9C39.9002 145.3 38.5002 146.7 37.0002 147.9C35.5002 149 33.3002 148.6 32.3002 147C32.0002 146.5 31.8002 146 31.7002 145.4C31.7002 140.5 31.7002 135.5 31.7002 130.6Z"
         fill="#764ABC"
       />
       <path
         d="M50.7998 58.5005C54.5998 58.6005 57.6998 55.6005 57.7998 51.8005C57.6998 48.0005 54.5998 45.0005 50.7998 45.0005C46.9998 44.9005 43.8998 47.9005 43.7998 51.7005C43.7998 55.5005 46.9998 58.6005 50.7998 58.5005Z"
         fill="#764ABC"
       />
     </svg>
    }
  />

  <Card
    title="Pirsch"
    href="/integrations/analytics/pirsch"
    horizontal
    icon={
    <><svg
         className="h-6 w-6 dark:hidden"
         width="1"
         height="1"
         viewBox="0 0 1 1"
         fill="none"
         xmlns="http://www.w3.org/2000/svg"
       >
         <g clipPath="url(#clip0_2199_68)">
           <path
             d="M0.184082 0.631579C0.358477 0.631579 0.499871 0.490184 0.499871 0.315789C0.499871 0.141395 0.358477 0 0.184082 0V0.631579ZM0.815661 0.368421C0.641266 0.368421 0.499871 0.509816 0.499871 0.684211C0.499871 0.858605 0.641266 1 0.815661 1V0.368421Z"
             fill="black"
           />
           <path
             d="M0.710681 0.288549C0.78335 0.288549 0.842259 0.229639 0.842259 0.15697C0.842259 0.0843005 0.78335 0.0253906 0.710681 0.0253906C0.638011 0.0253906 0.579102 0.0843005 0.579102 0.15697C0.579102 0.229639 0.638011 0.288549 0.710681 0.288549Z"
             fill="black"
           />
           <path
             d="M0.289294 0.974095C0.361963 0.974095 0.420873 0.915185 0.420873 0.842516C0.420873 0.769847 0.361963 0.710938 0.289294 0.710938C0.216625 0.710938 0.157715 0.769847 0.157715 0.842516C0.157715 0.915185 0.216625 0.974095 0.289294 0.974095Z"
             fill="black"
           />
         </g>
         <defs>
           <clipPath id="clip0_2199_68">
             <rect width="1" height="1" fill="black" />
           </clipPath>
         </defs>
       </svg>
       <svg
         className="hidden h-6 w-6 dark:block"
         width="1"
         height="1"
         viewBox="0 0 1 1"
         fill="none"
         xmlns="http://www.w3.org/2000/svg"
       >
         <g clipPath="url(#clip0_2199_68)">
           <path
             d="M0.184082 0.631579C0.358477 0.631579 0.499871 0.490184 0.499871 0.315789C0.499871 0.141395 0.358477 0 0.184082 0V0.631579ZM0.815661 0.368421C0.641266 0.368421 0.499871 0.509816 0.499871 0.684211C0.499871 0.858605 0.641266 1 0.815661 1V0.368421Z"
             fill="white"
           />
           <path
             d="M0.710681 0.288549C0.78335 0.288549 0.842259 0.229639 0.842259 0.15697C0.842259 0.0843005 0.78335 0.0253906 0.710681 0.0253906C0.638011 0.0253906 0.579102 0.0843005 0.579102 0.15697C0.579102 0.229639 0.638011 0.288549 0.710681 0.288549Z"
             fill="white"
           />
           <path
             d="M0.289294 0.974095C0.361963 0.974095 0.420873 0.915185 0.420873 0.842516C0.420873 0.769847 0.361963 0.710938 0.289294 0.710938C0.216625 0.710938 0.157715 0.769847 0.157715 0.842516C0.157715 0.915185 0.216625 0.974095 0.289294 0.974095Z"
             fill="white"
           />
         </g>
         <defs>
           <clipPath id="clip0_2199_68">
             <rect width="1" height="1" fill="white" />
           </clipPath>
         </defs>
       </svg>
       </>
    }
  />

  <Card
    title="Plausible"
    href="/integrations/analytics/plausible"
    horizontal
    icon={
     <svg
       xmlns="http://www.w3.org/2000/svg"
       width="1000px"
       height="1000px"
       className="h-6 w-6"
       viewBox="0 0 1000 1000"
     >
       <defs>
         <radialGradient
           cx="79.1305263%"
           cy="87.6448158%"
           fx="79.1305263%"
           fy="87.6448158%"
           r="96.9897763%"
           id="radialGradient-1"
         >
           <stop stopColor="#2440E6" offset="0%" />
           <stop stopColor="#5661B3" offset="100%" />
         </radialGradient>
         <radialGradient
           cx="0%"
           cy="30.2198829%"
           fx="0%"
           fy="30.2198829%"
           r="62.2688936%"
           gradientTransform="translate(0.000000,0.302199),scale(1.000000,0.722519),rotate(61.734530),translate(-0.000000,-0.302199)"
           id="radialGradient-2"
         >
           <stop stopColor="#6574CD" stopOpacity="0.5" offset="0%" />
           <stop stopColor="#6574CD" offset="100%" />
         </radialGradient>
       </defs>
       <g stroke="none" strokeWidth="1" fill="none" fillRule="evenodd">
         <g transform="translate(19.000000, 0.000000)">
           <g transform="translate(-19.000000, 0.000000)">
             <rect x="0" y="0" width="1000" height="1000" />
             <g transform="translate(124.069479, 0.000000)">
               <g transform="translate(376.923077, 500.000000) scale(-1, 1) rotate(-180.000000) translate(-376.923077, -500.000000) translate(2.233251, -0.000000)">
                 <circle
                   fill="url(#radialGradient-1)"
                   cx="373.69727"
                   cy="624.069479"
                   r="373.449132"
                 />
                 <path
                   d="M309.677419,993.322174 C232.506203,979.92267 167.493797,947.168328 113.647643,894.562869 C58.3126551,840.468576 24.0694789,777.44128 7.44416873,698.781231 L1.7369727,671.982223 L0.992555831,336.498352 L0.248138958,0.76634245 L7.19602978,0.76634245 C11.1662531,0.76634245 23.82134,2.00703724 35.235732,3.24773203 C132.754342,15.158402 215.632754,74.215474 260.794045,163.793638 C272.208437,186.622422 280.397022,212.925151 286.104218,245.679494 C290.818859,273.471057 291.066998,282.652199 290.322581,427.56535 L289.578164,580.170809 L295.533499,595.059146 C303.722084,615.406541 326.30273,637.987186 346.650124,646.175772 L361.538462,652.131107 L500.496278,652.379246 C576.923077,652.379246 643.920596,653.371802 649.131514,654.364357 C673.449132,659.078998 699.503722,679.426392 709.925558,702.007037 C712.903226,708.210511 716.873449,720.36932 718.610422,728.557906 C721.33995,742.205548 721.091811,745.927633 717.121588,761.312248 C704.71464,806.969816 661.042184,870.245251 616.377171,907.217955 C565.756824,949.153439 509.925558,977.193141 449.627792,991.337062 C417.866005,998.533092 345.905707,999.773787 309.677419,993.322174 Z"
                   id="Path"
                   fill="url(#radialGradient-2)"
                   fillRule="nonzero"
                 />
               </g>
             </g>
           </g>
         </g>
       </g>
     </svg>
    }
  />

  <Card
    title="Fathom"
    href="/integrations/analytics/fathom"
    horizontal
    icon={
    <svg
    className="h-6 w-6"
    width="256"
    height="256"
    viewBox="0 0 256 256"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
    >
    <path
     d="M50.4139 36.0859H40.3871C31.7927 36.105 22.7513 37.7857 15.3869 42.8984C11.5551 45.5505 8.45289 49.125 6.36656 53.292C4.0486 58.1293 2.89794 63.4429 3.0071 68.8058V212.667C3.0071 213.984 3.53027 215.247 4.46151 216.178C5.39275 217.109 6.65579 217.632 7.97276 217.632H27.5661C28.8831 217.632 30.1461 217.109 31.0774 216.178C32.0086 215.247 32.5318 213.984 32.5318 212.667V111.31H50.4063C51.0584 111.31 51.7041 111.182 52.3065 110.932C52.909 110.682 53.4564 110.317 53.9175 109.856C54.3786 109.394 54.7444 108.847 54.9939 108.245C55.2435 107.642 55.3719 106.996 55.3719 106.344V89.5566C55.3719 88.2396 54.8488 86.9766 53.9175 86.0453C52.9863 85.1141 51.7232 84.5909 50.4063 84.5909H32.5394V71.8349C32.4457 69.708 32.7382 67.5817 33.4027 65.5591C33.6012 64.974 33.9349 64.444 34.3767 64.0121C35.0566 63.4655 35.8835 63.1331 36.7526 63.0571C38.4628 62.845 40.1867 62.7639 41.9092 62.8146H50.4196C51.7366 62.8146 52.9996 62.2914 53.9309 61.3602C54.8621 60.4289 55.3853 59.1659 55.3853 57.8489V41.0592C55.3853 39.7423 54.8621 38.4792 53.9309 37.548C52.9996 36.6167 51.7366 36.0936 50.4196 36.0936"
     fill="#1F2026"
    />
    <path
     d="M168.815 128.261C168.982 122.018 167.781 115.814 165.296 110.084C162.812 104.354 159.105 99.2374 154.434 95.0918C145.198 87.0379 132.23 82.712 116.98 82.7178C101.466 82.7178 88.0641 87.1582 78.2799 94.9409C73.4171 98.7218 69.4331 103.513 66.6032 108.985C63.7733 114.456 62.165 120.476 61.8894 126.63C61.8575 127.301 61.9625 127.972 62.1977 128.602C62.433 129.232 62.7937 129.807 63.258 130.294C63.7223 130.78 64.2806 131.167 64.8989 131.431C65.5172 131.695 66.1827 131.831 66.855 131.83H87.6019C88.8467 131.832 90.0466 131.366 90.9642 130.525C91.8817 129.684 92.4499 128.529 92.5561 127.288C92.7767 124.972 93.4898 122.729 94.6475 120.71C95.8053 118.691 97.3811 116.943 99.2693 115.583C104.448 111.964 110.667 110.136 116.98 110.378C124.718 110.378 130.282 112.479 133.83 115.564C135.624 117.142 137.044 119.1 137.987 121.296C138.93 123.491 139.372 125.869 139.281 128.257V128.958C139.296 129.537 139.232 130.115 139.09 130.677L138.899 131.106C138.545 131.474 138.1 131.743 137.61 131.885C134.826 132.791 131.95 133.381 129.035 133.644C124.833 134.202 119.373 134.779 112.57 135.69H112.581C100.098 137.369 87.3498 139.41 77.0193 145.239C71.7347 148.136 67.3067 152.375 64.1812 157.527C60.8001 163.529 59.1166 170.338 59.311 177.224C59.2225 183.496 60.4876 189.713 63.02 195.452C66.6423 203.293 72.8442 209.656 80.5908 213.477C88.8782 217.474 97.9927 219.456 107.191 219.262C119.128 219.274 128.181 216.497 134.846 212.251C136.408 211.261 137.892 210.155 139.287 208.941V212.66C139.287 213.977 139.81 215.24 140.741 216.171C141.672 217.102 142.936 217.625 144.253 217.625H153.79L168.812 161.735L168.815 128.261ZM139.283 166.03C139.404 169.288 138.883 172.539 137.748 175.596C136.613 178.652 134.887 181.456 132.669 183.845C128.204 188.349 121.149 191.569 109.984 191.601C102.793 191.613 97.4741 190.033 94.2941 187.753C92.8266 186.744 91.6254 185.395 90.7933 183.821C89.9498 182.118 89.5217 180.241 89.5443 178.341V178.293V178.213C89.4842 176.061 90.0395 173.937 91.1447 172.09C93.1437 169.263 95.9722 167.127 99.2388 165.979C103.667 164.269 108.293 163.122 113.007 162.564C120.085 161.569 127.367 160.514 133.404 159.317C135.561 158.895 137.482 158.442 139.289 157.969L139.283 166.03Z"
     fill="#1F2026"
    />
    <path
     d="M251.975 21.9481C251.51 21.3425 250.913 20.8518 250.228 20.514C249.544 20.1763 248.791 20.0004 248.027 20H223.077C221.982 19.9988 220.917 20.3596 220.048 21.0263C219.18 21.6929 218.556 22.628 218.273 23.6861L168.813 207.74L166.375 216.833L163.015 229.322C162.816 230.059 162.789 230.832 162.937 231.581C163.085 232.33 163.404 233.035 163.868 233.641C164.333 234.247 164.931 234.737 165.616 235.074C166.301 235.411 167.055 235.586 167.818 235.584H192.769C193.863 235.586 194.927 235.226 195.796 234.56C196.665 233.895 197.289 232.961 197.572 231.904L252.831 26.2644C253.027 25.5271 253.053 24.7545 252.904 24.0059C252.756 23.2573 252.438 22.5527 251.975 21.9462"
     fill="#7166F6"
    />
    </svg>

    }
  />

  <Card
    title="Clearbit"
    href="/integrations/analytics/clearbit"
    horizontal
    icon={
     <svg
       xmlns="http://www.w3.org/2000/svg"
       width="36"
       height="36"
       className="h-6 w-6"
       viewBox="0 0 40 40"
     >
       <defs>
         <linearGradient id="clearbit-a" x1="50%" x2="100%" y1="0%" y2="100%">
           <stop offset="0%" stopColor="#DEF2FE"></stop>
           <stop offset="100%" stopColor="#DBF1FE"></stop>
         </linearGradient>
         <linearGradient id="clearbit-b" x1="0%" x2="50%" y1="0%" y2="100%">
           <stop offset="0%" stopColor="#57BCFD"></stop>
           <stop offset="100%" stopColor="#51B5FD"></stop>
         </linearGradient>
         <linearGradient id="clearbit-c" x1="37.5%" x2="62.5%" y1="0%" y2="100%">
           <stop offset="0%" stopColor="#1CA7FD"></stop>
           <stop offset="100%" stopColor="#148CFC"></stop>
         </linearGradient>
         <filter
           id="ck-icon-shadow"
           x="-50%"
           y="-50%"
           width="200%"
           height="200%"
         >
           <feOffset result="offOut" in="SourceGraphic" dx="0" dy="1"></feOffset>
           <feGaussianBlur
             result="blurOut"
             in="offOut"
             stdDeviation="1"
           ></feGaussianBlur>
           <feBlend in="SourceGraphic" in2="blurOut" mode="normal"></feBlend>
         </filter>
       </defs>
       <g fill="none">
         <path
           d="M27.9195733,37 L12.0804267,37 L11.4338943,36.9949826 C8.75934941,36.9515623 7.69554096,36.6271471 6.62367147,36.053905 C5.46935048,35.4365674 4.56343261,34.5306495 3.94609499,33.3763285 L3.81824005,33.1283803 C3.30403747,32.0897188 3.02217708,30.9433817 3.00125617,28.250264 L3,12.0804267 C3,8.92296455 3.32875737,7.77799245 3.94609499,6.62367147 C4.56343261,5.46935048 5.46935048,4.56343261 6.62367147,3.94609499 L6.87161969,3.81824005 C7.91028124,3.30403747 9.05661831,3.02217708 11.749736,3.00125617 L27.9195733,3 C31.0770355,3 32.2220075,3.32875737 33.3763285,3.94609499 C34.5306495,4.56343261 35.4365674,5.46935048 36.053905,6.62367147 L36.18176,6.87161969 C36.6959625,7.91028124 36.9778229,9.05661831 36.9987438,11.749736 L37,27.9195733 L36.9949826,28.5661057 C36.9515623,31.2406506 36.6271471,32.304459 36.053905,33.3763285 C35.4365674,34.5306495 34.5306495,35.4365674 33.3763285,36.053905 L33.1283803,36.18176 C32.0481723,36.7165306 30.8515024,37 27.9195733,37 Z"
           id="clearbit-edge"
           strokeOpacity="0.2"
           stroke="#9BADBC"
           fillOpacity="0"
           fill="#9BADBC"
         ></path>
         <path
           d="M27.9195733,37 L12.0804267,37 L11.4338943,36.9949826 C8.75934941,36.9515623 7.69554096,36.6271471 6.62367147,36.053905 C5.46935048,35.4365674 4.56343261,34.5306495 3.94609499,33.3763285 L3.81824005,33.1283803 C3.30403747,32.0897188 3.02217708,30.9433817 3.00125617,28.250264 L3,12.0804267 C3,8.92296455 3.32875737,7.77799245 3.94609499,6.62367147 C4.56343261,5.46935048 5.46935048,4.56343261 6.62367147,3.94609499 L6.87161969,3.81824005 C7.91028124,3.30403747 9.05661831,3.02217708 11.749736,3.00125617 L27.9195733,3 C31.0770355,3 32.2220075,3.32875737 33.3763285,3.94609499 C34.5306495,4.56343261 35.4365674,5.46935048 36.053905,6.62367147 L36.18176,6.87161969 C36.6959625,7.91028124 36.9778229,9.05661831 36.9987438,11.749736 L37,27.9195733 L36.9949826,28.5661057 C36.9515623,31.2406506 36.6271471,32.304459 36.053905,33.3763285 C35.4365674,34.5306495 34.5306495,35.4365674 33.3763285,36.053905 L33.1283803,36.18176 C32.0481723,36.7165306 30.8515024,37 27.9195733,37 Z"
           id="clearbit-fx"
           fillOpacity="0.2"
           fill="#9BADBC"
           filter="url(#ck-icon-shadow)"
         ></path>
         <path
           fill="url(#clearbit-a)"
           d="M37,20 L37,27.9195733 C37,31.0770355 36.6712426,32.2220075 36.053905,33.3763285 C35.4365674,34.5306495 34.5306495,35.4365674 33.3763285,36.053905 C32.2220075,36.6712426 31.0770355,37 27.9195733,37 L20,37 L20,20 L37,20 Z"
         ></path>
         <path
           fill="url(#clearbit-b)"
           d="M20,3 L27.9195733,3 C31.0770355,3 32.2220075,3.32875737 33.3763285,3.94609499 C34.5306495,4.56343261 35.4365674,5.46935048 36.053905,6.62367147 C36.6712426,7.77799245 37,8.92296455 37,12.0804267 L37,20 L20,20 L20,3 Z"
         ></path>
         <path
           fill="url(#clearbit-c)"
           d="M12.0804267,3 L20,3 L20,37 L12.0804267,37 C8.92296455,37 7.77799245,36.6712426 6.62367147,36.053905 C5.46935048,35.4365674 4.56343261,34.5306495 3.94609499,33.3763285 C3.32875737,32.2220075 3,31.0770355 3,27.9195733 L3,12.0804267 C3,8.92296455 3.32875737,7.77799245 3.94609499,6.62367147 C4.56343261,5.46935048 5.46935048,4.56343261 6.62367147,3.94609499 C7.77799245,3.32875737 8.92296455,3 12.0804267,3 Z"
         ></path>
       </g>
     </svg>
    }
  />

  <Card
    title="Heap"
    href="/integrations/analytics/heap"
    horizontal
    icon={
     <svg className="h-6 w-6" width="32" height="32" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M78.7 55.2H49V200.2H78.7V55.2ZM142.9 0H113.3V110.5H142.9V0Z" fill="black"/>
    <path d="M142.9 144.9H113.3V255.4H142.9V144.9ZM207.1 55.2002H177.5V200.2H207.1V55.2002Z" fill="#31D891"/>
    </svg>
    }
  />

  <Card
    title="Segment"
    href="/integrations/analytics/segment"
    horizontal
    icon={
     <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none">
       <path fill="#93C8A2" fill-rule="evenodd" d="M22.69 10.396H8.64a1.184 1.184 0 0 1-1.173-1.187c0-.653.528-1.188 1.173-1.188h14.05c.645 0 1.173.535 1.173 1.188 0 .653-.527 1.187-1.173 1.187Z" clip-rule="evenodd"/>
       <path fill="#43AF79" fill-rule="evenodd" d="M1.923 10.396A1.184 1.184 0 0 1 .75 9.209c0-.12.03-.238.059-.356C2.275 4.015 6.646.75 11.66.75c1.144 0 2.288.178 3.374.505.615.207.968.86.762 1.484-.205.623-.85.979-1.466.771a8.962 8.962 0 0 0-2.67-.415c-3.989 0-7.45 2.582-8.594 6.44-.176.505-.616.86-1.144.86Z" clip-rule="evenodd"/>
       <path fill="#93C8A2" fill-rule="evenodd" d="M19.786 4.667c0 .653-.528 1.188-1.173 1.188a1.184 1.184 0 0 1-1.173-1.188c0-.653.528-1.187 1.173-1.187s1.173.534 1.173 1.187ZM1.173 13.604h14.05c.645 0 1.173.534 1.173 1.187s-.528 1.188-1.173 1.188H1.173A1.184 1.184 0 0 1 0 14.79c0-.653.528-1.187 1.173-1.187Z" clip-rule="evenodd"/>
       <path fill="#43AF79" fill-rule="evenodd" d="M21.94 13.604c.645 0 1.173.534 1.173 1.187 0 .12-.029.238-.058.357-1.467 4.837-5.837 8.102-10.853 8.102-1.144 0-2.288-.178-3.373-.505-.616-.207-.968-.86-.763-1.483.205-.624.85-.98 1.467-.772.85.267 1.76.415 2.669.415 3.989 0 7.45-2.582 8.594-6.44.176-.505.616-.86 1.144-.86Z" clip-rule="evenodd"/>
       <path fill="#93C8A2" fill-rule="evenodd" d="M4.077 19.332c0-.653.528-1.187 1.173-1.187.646 0 1.174.534 1.174 1.187S5.896 20.52 5.25 20.52a1.184 1.184 0 0 1-1.173-1.188Z" clip-rule="evenodd"/>
     </svg>
    }
  />
</CardGroup>

## Enabling Analytics

Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free.

The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "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
  "analytics": {
      "ga4": {
          "measurementId": "G-XXXXXXX"
      }
  }
  ```
</CodeGroup>


# Pirsch



Add the following to your `mint.json` file to send analytics to Pirsch.

You can get your site ID from Settings > Developer > Identification Code.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "pirsch": {
          "id": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "pirsch": {
          "id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp"
      }
  }
  ```
</CodeGroup>


# Plausible



Add your site's domain to `mint.json` to send analytics to Plausible.

<Info>
  Do not include `http://` or `https://` with your domain.
</Info>

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "plausible": {
          "domain": "required"
      }
  }
  ```

  ```json Example
  "analytics": {
      "plausible": {
          "domain": "docs.domain.com"
      }
  }
  ```
</CodeGroup>


# PostHog



Add the following to your `mint.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.

<CodeGroup>
  ```json Analytics options in mint.json
  "analytics": {
      "posthog": {
          "apiKey": "required",
          "apiHost": "optional"
      }
  }
  ```

  ```json Example
  "analytics": {
      "posthog": {
          "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW"
      }
  }
  ```
</CodeGroup>

<br />

<Warning>
  Enabling PostHog analytics will disable the analytics on the Mintlify dashboard.
</Warning>

## 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.


# Osano



Add the following to your `mint.json` file to add the [Osano](https://www.osano.com/) cookie consent manager.

<CodeGroup>
  ```json Integration options in mint.json
  "integrations": {
      "osano": "SOURCE"
  }
  ```

  ```json Example
  "integrations": {
      "osano": "https://cmp.osano.com/2sUB2dqwqdkks/8dqwd-dwd86£-4a9b/osano.js"
  }
  ```
</CodeGroup>

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
<script src="https://cmp.osano.com/placeholder/placeholder/osano.js"/>
```


# Privacy Integrations

Integrate with a data privacy platform

<CardGroup>
  <Card title="Osano" href="/integrations/privacy/osano" icon={<svg width="32" height="32" className="h-6 w-6" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg"><path fillRule="evenodd" clipRule="evenodd" d="M128 256C198.692 256 256 198.692 256 128C256 57.3076 198.692 0 128 0C57.3076 0 0 57.3076 0 128C0 198.692 57.3076 256 128 256ZM128 192C163.346 192 192 163.346 192 128C192 92.6538 163.346 64 128 64C92.6538 64 64 92.6538 64 128C64 163.346 92.6538 192 128 192Z" fill="#7764FA"/></svg>} horizontal />
</CardGroup>

## Enabling Data Privacy Integrations

You can add data privacy platforms onto your docs. Add the `integrations` field into your `mint.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

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.

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/speakeasy-1.webp)

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

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/speakeasy-2.webp)

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

![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/speakeasy-3.webp)

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

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



Add the following to your `mint.json` file to add a [Front Chat](https://front.com) widget.

<CodeGroup>
  ```json Integration options in mint.json
  "integrations": {
      "frontchat": "CHAT_ID"
  }
  ```

  ```json Example
  "integrations": {
      "frontchat": "1365d046d7c023e9b030ce90d02d093a"
  }
  ```
</CodeGroup>


# Intercom



Add the following to your `mint.json` file to add an [Intercom](https://www.intercom.com) widget.

<CodeGroup>
  ```json Integration options in mint.json
  "integrations": {
      "intercom": "APP_ID"
  }
  ```

  ```json Example
  "integrations": {
      "intercom": "x2pg8cwb"
  }
  ```
</CodeGroup>


# Support Integrations

Integrate with a support widget

<CardGroup>
  <Card title="Intercom" href="/integrations/support/intercom" icon={<svg className="h-6 w-6" width="2500" height="2500" viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M221.867 140.748a8.534 8.534 0 0 1-17.067 0V64a8.534 8.534 0 0 1 17.067 0v76.748zm-2.978 53.413c-1.319 1.129-32.93 27.655-90.889 27.655-57.958 0-89.568-26.527-90.887-27.656a8.535 8.535 0 0 1-.925-12.033 8.53 8.53 0 0 1 12.013-.942c.501.42 28.729 23.563 79.8 23.563 51.712 0 79.503-23.31 79.778-23.545 3.571-3.067 8.968-2.655 12.033.925a8.534 8.534 0 0 1-.923 12.033zM34.133 64A8.534 8.534 0 0 1 51.2 64v76.748a8.534 8.534 0 0 1-17.067 0V64zm42.668-17.067a8.534 8.534 0 0 1 17.066 0v114.001a8.534 8.534 0 0 1-17.066 0v-114zm42.666-4.318A8.532 8.532 0 0 1 128 34.082a8.532 8.532 0 0 1 8.534 8.533v123.733a8.534 8.534 0 0 1-17.067 0V42.615zm42.667 4.318a8.534 8.534 0 0 1 17.066 0v114.001a8.534 8.534 0 0 1-17.066 0v-114zM224 0H32C14.327 0 0 14.327 0 32v192c0 17.672 14.327 32 32 32h192c17.673 0 32-14.328 32-32V32c0-17.673-14.327-32-32-32z" fill="#1F8DED"/></svg>} horizontal />

  <Card
    href="/integrations/support/front"
    title="Front"
    icon={<svg className="h-6 w-6" width="754" height="754" viewBox="0 0 754 754" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M124 135.5C124 69 177.9 15 244.5 15H630.8V186.4C630.8 219.7 603.8 246.6 570.6 246.6H413.6C381.6 246.6 355.7 272.5 355.7 304.5V678.7C355.7 712 328.7 738.9 295.5 738.9H124V135.5Z" fill="#001B38"/>
    <path d="M415 462.4C501.377 462.4 571.4 392.377 571.4 306C571.4 219.623 501.377 149.6 415 149.6C328.623 149.6 258.6 219.623 258.6 306C258.6 392.377 328.623 462.4 415 462.4Z" fill="url(#paint0_linear_66_11)"/>
    <path opacity="0.5" d="M415 462.4C501.377 462.4 571.4 392.377 571.4 306C571.4 219.623 501.377 149.6 415 149.6C328.623 149.6 258.6 219.623 258.6 306C258.6 392.377 328.623 462.4 415 462.4Z" fill="url(#paint1_linear_66_11)"/>
    <defs>
    <linearGradient id="paint0_linear_66_11" x1="301.703" y1="191.962" x2="536.873" y2="428.762" gradientUnits="userSpaceOnUse">
    <stop stopColor="#FF0057" stopOpacity="0.16"/>
    <stop offset="0.86" stopColor="#FF0057"/>
    </linearGradient>
    <linearGradient id="paint1_linear_66_11" x1="301.703" y1="191.962" x2="536.873" y2="428.762" gradientUnits="userSpaceOnUse">
    <stop stopColor="#FF0057" stopOpacity="0.16"/>
    <stop offset="0.86" stopColor="#FF0057"/>
    </linearGradient>
    </defs>
    </svg>
    }
    horizontal
  />
</CardGroup>

## Enabling Support Integrations

You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `mint.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

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
```

<Tip>
  Lists follow the official [markdown syntax](https://www.markdownguide.org/basic-syntax/#lists-1).
</Tip>

## Tables

| Property | Description                           |
| -------- | ------------------------------------- |
| Name     | Full name of user                     |
| Age      | Reported age                          |
| Joined   | Whether the user joined the community |

### Creating a table

<Tip>
  The Table component follows the official [markdown syntax](https://www.markdownguide.org/extended-syntax/#tables).
</Tip>

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

How to migrate documentation from your existing provider

You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to scrape documentation frameworks to Mintlify.

We currently support migration for:

<CardGroup cols={2}>
  <Card
    title="Docusaurus"
    horizontal
    icon={<svg className="h-6 w-6" width="36" height="36" viewBox="0 -19 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid">
       <g>
       		<rect fill="#FFFFFF" x="126.030769" y="45.9487179" width="110.276923" height="44.6358974">

    </rect>
       		<path d="M26.2564103,191.671795 C16.5441641,191.671795 8.0830359,186.385067 3.54067692,178.54359 C1.30231795,182.408533 0,186.883938 0,191.671795 C0,206.17321 11.7549949,217.928205 26.2564103,217.928205 L52.5128205,217.928205 L52.5128205,191.671795 L26.2564103,191.671795 Z" fill="#3ECC5F">

    </path>
       		<path d="M144.384656,53.006441 L236.308349,47.2615385 L236.308349,34.1333333 C236.308349,19.6319179 224.552041,7.87692308 210.051938,7.87692308 L91.8980923,7.87692308 L88.616041,2.19241026 C87.1561846,-0.334769231 83.5104821,-0.334769231 82.0519385,2.19241026 L78.7698872,7.87692308 L75.4878359,2.19241026 C74.0279795,-0.334769231 70.3822769,-0.334769231 68.9237333,2.19241026 L65.6416821,7.87692308 L62.3596308,2.19241026 C60.8997744,-0.334769231 57.2540718,-0.334769231 55.7955282,2.19241026 L52.5134769,7.87692308 C52.4845949,7.87692308 52.4570256,7.88086154 52.4281436,7.88086154 L46.990441,2.44447179 C44.928,0.382030769 41.4070154,1.3246359 40.6508308,4.14326154 L38.8548923,10.8438974 L32.0374154,9.01645128 C29.2187897,8.26157949 26.6404103,10.839959 27.3965949,13.6585846 L29.2227282,20.4760615 L22.5234051,22.2706872 C19.7047795,23.0268718 18.7608615,26.5491692 20.8233026,28.6116103 L26.2596923,34.0493128 C26.2596923,34.0768821 26.2570667,34.1044513 26.2570667,34.1333333 L20.571241,37.4153846 C18.0453744,38.8739282 18.0453744,42.5209436 20.571241,43.9794872 L26.2570667,47.2615385 L20.571241,50.5435897 C18.0453744,52.0021333 18.0453744,55.6491487 20.571241,57.1076923 L26.2570667,60.3897436 L20.571241,63.6717949 C18.0453744,65.1303385 18.0453744,68.7773538 20.571241,70.2358974 L26.2570667,73.5179487 L20.571241,76.8 C18.0453744,78.2585436 18.0453744,81.905559 20.571241,83.3641026 L26.2570667,86.6461538 L20.571241,89.9282051 C18.0453744,91.3867487 18.0453744,95.0337641 20.571241,96.4923077 L26.2570667,99.774359 L20.571241,103.05641 C18.0453744,104.514954 18.0453744,108.161969 20.571241,109.620513 L26.2570667,112.902564 L20.571241,116.184615 C18.0453744,117.643159 18.0453744,121.290174 20.571241,122.748718 L26.2570667,126.030769 L20.571241,129.312821 C18.0453744,130.771364 18.0453744,134.418379 20.571241,135.876923 L26.2570667,139.158974 L20.571241,142.441026 C18.0453744,143.899569 18.0453744,147.546585 20.571241,149.005128 L26.2570667,152.287179 L20.571241,155.569231 C18.0453744,157.027774 18.0453744,160.67479 20.571241,162.133333 L26.2570667,165.415385 L20.571241,168.697436 C18.0453744,170.155979 18.0453744,173.802995 20.571241,175.261538 L26.2570667,178.54359 L20.571241,181.825641 C18.0453744,183.284185 18.0453744,186.9312 20.571241,188.389744 L26.2570667,191.671795 C26.2570667,206.17321 38.0120615,217.928205 52.5134769,217.928205 L210.051938,217.928205 C224.552041,217.928205 236.308349,206.17321 236.308349,191.671795 L236.308349,86.6461538 L144.384656,80.9012513 C137.019733,80.4404513 131.282708,74.3332103 131.282708,66.9538462 C131.282708,59.5744821 137.019733,53.467241 144.384656,53.006441" fill="#3ECC5F">

    </path>
       		<polygon fill="#3ECC5F" points="183.794872 217.928205 223.179487 217.928205 223.179487 165.415385 183.794872 165.415385">

    </polygon>
       		<path d="M249.435897,185.107692 C249.14839,185.107692 248.87401,185.156267 248.597005,185.191713 C248.547118,184.99479 248.499856,184.796554 248.444718,184.599631 C250.815672,183.609764 252.481641,181.272944 252.481641,178.54359 C252.481641,174.917579 249.543549,171.979487 245.917538,171.979487 C244.423549,171.979487 243.062154,172.499364 241.958072,173.339569 C241.812349,173.191221 241.666626,173.044185 241.518277,172.898462 C242.341415,171.800944 242.845538,170.45399 242.845538,168.977067 C242.845538,165.351056 239.907446,162.412964 236.281436,162.412964 C233.570462,162.412964 231.244144,164.057928 230.243774,166.405251 C230.049477,166.350113 229.853867,166.304164 229.659569,166.254277 C229.695015,165.977272 229.74359,165.702892 229.74359,165.415385 C229.74359,161.789374 226.805497,158.851282 223.179487,158.851282 C219.553477,158.851282 216.615385,161.789374 216.615385,165.415385 C216.615385,165.702892 216.663959,165.977272 216.699405,166.254277 C216.505108,166.304164 216.309497,166.350113 216.1152,166.405251 C215.114831,164.057928 212.788513,162.412964 210.077538,162.412964 C206.451528,162.412964 203.513436,165.351056 203.513436,168.977067 C203.513436,170.45399 204.017559,171.800944 204.840697,172.898462 C199.960944,177.666626 196.923077,184.31081 196.923077,191.671795 C196.923077,206.17321 208.678072,217.928205 223.179487,217.928205 C235.439918,217.928205 245.707487,209.513026 248.597005,198.151877 C248.87401,198.187323 249.14839,198.235897 249.435897,198.235897 C253.061908,198.235897 256,195.297805 256,191.671795 C256,188.045785 253.061908,185.107692 249.435897,185.107692" fill="#44D860">

    </path>
       		<polygon fill="#3ECC5F" points="196.923077 139.158974 236.307692 139.158974 236.307692 112.902564 196.923077 112.902564">

    </polygon>
       		<path d="M249.435897,129.312821 C251.248903,129.312821 252.717949,127.843774 252.717949,126.030769 C252.717949,124.217764 251.248903,122.748718 249.435897,122.748718 C249.2928,122.748718 249.154954,122.773662 249.017108,122.790728 C248.990851,122.692267 248.968533,122.593805 248.940964,122.495344 C250.125128,122.00041 250.958769,120.830687 250.958769,119.466667 C250.958769,117.653662 249.489723,116.184615 247.676718,116.184615 C246.929723,116.184615 246.248369,116.443241 245.696985,116.864656 C245.624779,116.789826 245.551262,116.716308 245.476431,116.644103 C245.888656,116.096656 246.140718,115.421867 246.140718,114.682749 C246.140718,112.871056 244.671672,111.400697 242.858667,111.400697 C241.502523,111.400697 240.339364,112.223836 239.839179,113.397497 C238.714092,113.083733 237.533867,112.902564 236.307692,112.902564 C229.058297,112.902564 223.179487,118.781374 223.179487,126.030769 C223.179487,133.280164 229.058297,139.158974 236.307692,139.158974 C237.533867,139.158974 238.714092,138.977805 239.839179,138.664041 C240.339364,139.837703 241.502523,140.660841 242.858667,140.660841 C244.671672,140.660841 246.140718,139.190482 246.140718,137.37879 C246.140718,136.639672 245.888656,135.964882 245.476431,135.417436 C245.551262,135.345231 245.624779,135.271713 245.696985,135.196882 C246.248369,135.618297 246.929723,135.876923 247.676718,135.876923 C249.489723,135.876923 250.958769,134.407877 250.958769,132.594872 C250.958769,131.230851 250.125128,130.061128 248.940964,129.566195 C248.968533,129.469046 248.990851,129.369272 249.017108,129.27081 C249.154954,129.287877 249.2928,129.312821 249.435897,129.312821" fill="#44D860">

    </path>
       		<path d="M78.7692308,50.5435897 C76.9562256,50.5435897 75.4871795,49.0745436 75.4871795,47.2615385 C75.4871795,41.8317128 71.0708513,37.4153846 65.6410256,37.4153846 C60.2112,37.4153846 55.7948718,41.8317128 55.7948718,47.2615385 C55.7948718,49.0745436 54.3258256,50.5435897 52.5128205,50.5435897 C50.6998154,50.5435897 49.2307692,49.0745436 49.2307692,47.2615385 C49.2307692,38.2122667 56.5917538,30.8512821 65.6410256,30.8512821 C74.6902974,30.8512821 82.0512821,38.2122667 82.0512821,47.2615385 C82.0512821,49.0745436 80.5822359,50.5435897 78.7692308,50.5435897" fill="#000000">

    </path>
       		<path d="M131.282051,217.928205 L210.051282,217.928205 C224.552697,217.928205 236.307692,206.17321 236.307692,191.671795 L236.307692,99.774359 L157.538462,99.774359 C143.037046,99.774359 131.282051,111.529354 131.282051,126.030769 L131.282051,217.928205 Z" fill="#FFFF50">

    </path>
       		<path d="M216.640985,140.471795 L150.948759,140.471795 C150.222769,140.471795 149.635938,139.884964 149.635938,139.158974 C149.635938,138.432985 150.222769,137.846154 150.948759,137.846154 L216.640985,137.846154 C217.366974,137.846154 217.953805,138.432985 217.953805,139.158974 C217.953805,139.884964 217.366974,140.471795 216.640985,140.471795" fill="#000000">

    </path>
       		<path d="M216.640985,166.728205 L150.948759,166.728205 C150.222769,166.728205 149.635938,166.141374 149.635938,165.415385 C149.635938,164.689395 150.222769,164.102564 150.948759,164.102564 L216.640985,164.102564 C217.366974,164.102564 217.953805,164.689395 217.953805,165.415385 C217.953805,166.141374 217.366974,166.728205 216.640985,166.728205" fill="#000000">

    </path>
       		<path d="M216.640985,192.984615 L150.948759,192.984615 C150.222769,192.984615 149.635938,192.397785 149.635938,191.671795 C149.635938,190.945805 150.222769,190.358974 150.948759,190.358974 L216.640985,190.358974 C217.366974,190.358974 217.953805,190.945805 217.953805,191.671795 C217.953805,192.397785 217.366974,192.984615 216.640985,192.984615" fill="#000000">

    </path>
       		<path d="M216.640985,127.587118 L150.948759,127.587118 C150.222769,127.587118 149.635938,126.998974 149.635938,126.274297 C149.635938,125.548308 150.222769,124.961477 150.948759,124.961477 L216.640985,124.961477 C217.366974,124.961477 217.953805,125.548308 217.953805,126.274297 C217.953805,126.998974 217.366974,127.587118 216.640985,127.587118" fill="#000000">

    </path>
       		<path d="M216.640985,153.6 L150.948759,153.6 C150.222769,153.6 149.635938,153.013169 149.635938,152.287179 C149.635938,151.56119 150.222769,150.974359 150.948759,150.974359 L216.640985,150.974359 C217.366974,150.974359 217.953805,151.56119 217.953805,152.287179 C217.953805,153.013169 217.366974,153.6 216.640985,153.6" fill="#000000">

    </path>
       		<path d="M216.640985,179.85641 L150.948759,179.85641 C150.222769,179.85641 149.635938,179.269579 149.635938,178.54359 C149.635938,177.8176 150.222769,177.230769 150.948759,177.230769 L216.640985,177.230769 C217.366974,177.230769 217.953805,177.8176 217.953805,178.54359 C217.953805,179.269579 217.366974,179.85641 216.640985,179.85641" fill="#000000">

    </path>
       		<path d="M236.307692,58.5666297 C236.291938,58.5666297 236.27881,58.5587528 236.263056,58.5600656 C232.206441,58.6979118 230.287097,62.75584 228.593559,66.3359015 C226.826503,70.0761272 225.459856,72.5100964 223.220185,72.4365785 C220.740267,72.3473067 219.322421,69.5457477 217.820554,66.5800862 C216.095508,63.1759426 214.126277,59.3136246 209.992205,59.4580349 C205.993354,59.5945682 204.067446,63.1260554 202.368656,66.2413785 C200.560903,69.5601887 199.33079,71.5779938 196.958523,71.4847836 C194.428718,71.3928862 193.08439,69.1151426 191.528697,66.478999 C189.794462,63.5435323 187.789785,60.2431015 183.735795,60.3560041 C179.80521,60.4912246 177.874051,63.487081 176.17001,66.1324144 C174.367508,68.9287221 173.104574,70.6327631 170.702113,70.5316759 C168.111918,70.4384656 166.774154,68.5493169 165.226338,66.3608451 C163.488164,63.9019323 161.529436,61.1187528 157.487262,61.2539733 C153.643323,61.3852554 151.712164,63.8389169 150.009436,66.0037579 C148.392041,68.0570092 147.129108,69.682281 144.457518,69.579881 C143.732841,69.550999 143.125005,70.1194503 143.098749,70.84544 C143.071179,71.5688041 143.638318,72.1779528 144.362995,72.2055221 C148.323774,72.3381169 150.329764,69.8411323 152.071877,67.6277169 C153.617067,65.6637374 154.950892,63.9688862 157.576533,63.8796144 C160.105026,63.7719631 161.290503,65.3434092 163.083815,67.8771528 C164.786544,70.2848656 166.719015,73.0155323 170.60759,73.1560041 C174.681272,73.2925374 176.641313,70.2481067 178.376862,67.554199 C179.928615,65.1464862 181.267692,63.0682913 183.825067,62.9803323 C186.178954,62.8923733 187.460267,64.75264 189.266708,67.8128246 C190.969436,70.6970913 192.897969,73.9647015 196.864,74.1091118 C200.966564,74.2508964 202.94761,70.6682092 204.673969,67.4990605 C206.169272,64.7578913 207.580554,62.1676964 210.081477,62.0823631 C212.435364,62.0272246 213.662851,64.1763118 215.478482,67.7668759 C217.174646,71.1185067 219.097928,74.9151836 223.125662,75.0609067 C223.200492,75.0635323 223.27401,75.0648451 223.347528,75.0648451 C227.37001,75.0648451 229.278851,71.0279221 230.968451,67.4583631 C232.463754,64.2944656 233.878974,61.3130503 236.307692,61.1922708 L236.307692,58.5666297 Z" fill="#000000">

    </path>
       		<polygon fill="#3ECC5F" points="105.025641 217.928205 157.538462 217.928205 157.538462 165.415385 105.025641 165.415385">

    </polygon>
       		<path d="M183.794872,185.107692 C183.507364,185.107692 183.232985,185.156267 182.955979,185.191713 C182.906092,184.99479 182.858831,184.796554 182.803692,184.599631 C185.174646,183.609764 186.840615,181.272944 186.840615,178.54359 C186.840615,174.917579 183.902523,171.979487 180.276513,171.979487 C178.782523,171.979487 177.421128,172.499364 176.317046,173.339569 C176.171323,173.191221 176.0256,173.044185 175.877251,172.898462 C176.70039,171.800944 177.204513,170.45399 177.204513,168.977067 C177.204513,165.351056 174.266421,162.412964 170.64041,162.412964 C167.929436,162.412964 165.603118,164.057928 164.602749,166.405251 C164.408451,166.350113 164.212841,166.304164 164.018544,166.254277 C164.05399,165.977272 164.102564,165.702892 164.102564,165.415385 C164.102564,161.789374 161.164472,158.851282 157.538462,158.851282 C153.912451,158.851282 150.974359,161.789374 150.974359,165.415385 C150.974359,165.702892 151.022933,165.977272 151.058379,166.254277 C150.864082,166.304164 150.668472,166.350113 150.474174,166.405251 C149.473805,164.057928 147.147487,162.412964 144.436513,162.412964 C140.810503,162.412964 137.87241,165.351056 137.87241,168.977067 C137.87241,170.45399 138.376533,171.800944 139.199672,172.898462 C134.319918,177.666626 131.282051,184.31081 131.282051,191.671795 C131.282051,206.17321 143.037046,217.928205 157.538462,217.928205 C169.798892,217.928205 180.066462,209.513026 182.955979,198.151877 C183.232985,198.187323 183.507364,198.235897 183.794872,198.235897 C187.420882,198.235897 190.358974,195.297805 190.358974,191.671795 C190.358974,188.045785 187.420882,185.107692 183.794872,185.107692" fill="#44D860">

    </path>
       		<polygon fill="#3ECC5F" points="105.025641 139.158974 157.538462 139.158974 157.538462 112.902564 105.025641 112.902564">

    </polygon>
       		<path d="M170.666667,129.312821 C172.479672,129.312821 173.948718,127.843774 173.948718,126.030769 C173.948718,124.217764 172.479672,122.748718 170.666667,122.748718 C170.523569,122.748718 170.385723,122.773662 170.247877,122.790728 C170.221621,122.692267 170.199303,122.593805 170.171733,122.495344 C171.355897,122.00041 172.189538,120.830687 172.189538,119.466667 C172.189538,117.653662 170.720492,116.184615 168.907487,116.184615 C168.160492,116.184615 167.479138,116.443241 166.927754,116.864656 C166.855549,116.789826 166.782031,116.716308 166.7072,116.644103 C167.119426,116.096656 167.371487,115.421867 167.371487,114.682749 C167.371487,112.871056 165.902441,111.400697 164.089436,111.400697 C162.733292,111.400697 161.570133,112.223836 161.069949,113.397497 C159.944862,113.083733 158.764636,112.902564 157.538462,112.902564 C150.289067,112.902564 144.410256,118.781374 144.410256,126.030769 C144.410256,133.280164 150.289067,139.158974 157.538462,139.158974 C158.764636,139.158974 159.944862,138.977805 161.069949,138.664041 C161.570133,139.837703 162.733292,140.660841 164.089436,140.660841 C165.902441,140.660841 167.371487,139.190482 167.371487,137.37879 C167.371487,136.639672 167.119426,135.964882 166.7072,135.417436 C166.782031,135.345231 166.855549,135.271713 166.927754,135.196882 C167.479138,135.618297 168.160492,135.876923 168.907487,135.876923 C170.720492,135.876923 172.189538,134.407877 172.189538,132.594872 C172.189538,131.230851 171.355897,130.061128 170.171733,129.566195 C170.199303,129.469046 170.221621,129.369272 170.247877,129.27081 C170.385723,129.287877 170.523569,129.312821 170.666667,129.312821" fill="#44D860">

    </path>
       		<path d="M183.794872,32.4923077 C183.584821,32.4923077 183.361641,32.4660513 183.15159,32.4266667 C182.941538,32.3872821 182.730174,32.321641 182.534564,32.2428718 C182.337641,32.1641026 182.153846,32.0590769 181.968738,31.9409231 C181.798072,31.8227692 181.628718,31.678359 181.469867,31.5339487 C181.326769,31.3764103 181.182359,31.2188718 181.064205,31.0350769 C180.946051,30.8512821 180.841026,30.6674872 180.760944,30.4705641 C180.683487,30.273641 180.617846,30.0635897 180.578462,29.8535385 C180.539077,29.6434872 180.512821,29.4203077 180.512821,29.2102564 C180.512821,29.0002051 180.539077,28.7770256 180.578462,28.5669744 C180.617846,28.3569231 180.683487,28.16 180.760944,27.9499487 C180.841026,27.7530256 180.946051,27.5692308 181.064205,27.3854359 C181.182359,27.2147692 181.326769,27.0441026 181.469867,26.8865641 C181.628718,26.7421538 181.798072,26.5977436 181.968738,26.4795897 C182.153846,26.3614359 182.337641,26.2564103 182.534564,26.177641 C182.730174,26.0988718 182.941538,26.0332308 183.15159,25.9938462 C183.571692,25.9019487 184.004923,25.9019487 184.438154,25.9938462 C184.646892,26.0332308 184.858256,26.0988718 185.055179,26.177641 C185.25079,26.2564103 185.435897,26.3614359 185.619692,26.4795897 C185.790359,26.5977436 185.959713,26.7421538 186.118564,26.8865641 C186.262974,27.0441026 186.407385,27.2147692 186.525538,27.3854359 C186.643692,27.5692308 186.748718,27.7530256 186.827487,27.9499487 C186.906256,28.16 186.971897,28.3569231 187.011282,28.5669744 C187.049354,28.7770256 187.076923,29.0002051 187.076923,29.2102564 C187.076923,30.0767179 186.721149,30.9300513 186.118564,31.5339487 C185.959713,31.678359 185.790359,31.8227692 185.619692,31.9409231 C185.435897,32.0590769 185.25079,32.1641026 185.055179,32.2428718 C184.858256,32.321641 184.646892,32.3872821 184.438154,32.4266667 C184.228103,32.4660513 184.004923,32.4923077 183.794872,32.4923077" fill="#000000">

    </path>
       		<path d="M210.051282,30.8512821 C209.184821,30.8512821 208.344615,30.4968205 207.726277,29.8929231 C207.583179,29.7353846 207.438769,29.5647179 207.320615,29.3940513 C207.202462,29.2102564 207.097436,29.0264615 207.017354,28.8295385 C206.939897,28.6326154 206.874256,28.4225641 206.834872,28.2125128 C206.795487,28.0024615 206.769231,27.7792821 206.769231,27.5692308 C206.769231,26.7027692 207.123692,25.8625641 207.726277,25.2455385 C207.885128,25.1011282 208.054482,24.9567179 208.225149,24.8385641 C208.410256,24.7204103 208.594051,24.6153846 208.790974,24.5366154 C208.986585,24.4578462 209.197949,24.3922051 209.408,24.3528205 C209.828103,24.2609231 210.274462,24.2609231 210.694564,24.3528205 C210.903303,24.3922051 211.114667,24.4578462 211.31159,24.5366154 C211.5072,24.6153846 211.692308,24.7204103 211.876103,24.8385641 C212.046769,24.9567179 212.216123,25.1011282 212.374974,25.2455385 C212.977559,25.8625641 213.333333,26.7027692 213.333333,27.5692308 C213.333333,27.7792821 213.305764,28.0024615 213.267692,28.2125128 C213.228308,28.4225641 213.162667,28.6326154 213.083897,28.8295385 C212.992,29.0264615 212.900103,29.2102564 212.781949,29.3940513 C212.663795,29.5647179 212.519385,29.7353846 212.374974,29.8929231 C212.216123,30.0373333 212.046769,30.1817436 211.876103,30.2998974 C211.692308,30.4180513 211.5072,30.5230769 211.31159,30.6018462 C211.114667,30.6806154 210.903303,30.7462564 210.694564,30.785641 C210.484513,30.8250256 210.261333,30.8512821 210.051282,30.8512821" fill="#000000">

    </path>
       </g>
    </svg>}
  />

  <Card
    title="GitBook"
    horizontal
    icon={<svg className="h-6 w-6" width="36" height="36" viewBox="0 0 65 65" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M27.3964 34.2196C30.5255 36.0256 32.09 36.9286 33.8083 36.9301C35.5265 36.9316 37.0926 36.0314 40.2249 34.2308L60.1914 22.7535C61.0927 22.2354 61.6484 21.275 61.6484 20.2353C61.6484 19.1956 61.0927 18.2352 60.1914 17.7171L40.2177 6.23561C37.0888 4.43703 35.5243 3.53774 33.8078 3.53841C32.0912 3.53908 30.5275 4.43959 27.4 6.24061L10.2293 16.1287C10.102 16.202 10.0384 16.2386 9.97907 16.2733C4.1137 19.7069 0.489885 25.9755 0.441431 32.7718C0.440941 32.8405 0.440941 32.9139 0.440941 33.0608C0.440941 33.2075 0.440941 33.2808 0.44143 33.3494C0.489777 40.1381 4.10551 46.4008 9.96043 49.8371C10.0196 49.8719 10.0831 49.9085 10.2102 49.9819L20.9659 56.1919C27.2332 59.8105 30.3668 61.6197 33.8081 61.6209C37.2493 61.6221 40.3842 59.8149 46.6539 56.2006L58.008 49.6552C61.1474 47.8454 62.7171 46.9406 63.579 45.4488C64.4409 43.957 64.4409 42.1452 64.4409 38.5215V31.5213C64.4409 30.516 63.8965 29.5896 63.0182 29.1004C62.1683 28.6271 61.1325 28.6341 60.2891 29.1189L37.0074 42.5019C35.4454 43.3999 34.6643 43.8488 33.8072 43.8491C32.9502 43.8493 32.1689 43.4008 30.6063 42.5039L14.8487 33.4587C14.0594 33.0056 13.6647 32.779 13.3477 32.7381C12.625 32.6449 11.9301 33.0497 11.6548 33.7244C11.5341 34.0204 11.5365 34.4754 11.5414 35.3855C11.545 36.0556 11.5468 36.3906 11.6094 36.6987C11.7497 37.3888 12.1127 38.0137 12.6428 38.4772C12.8795 38.6842 13.1696 38.8517 13.7499 39.1866L30.5974 48.9103C32.1641 49.8145 32.9474 50.2666 33.8075 50.2669C34.6677 50.2671 35.4513 49.8154 37.0184 48.9121L57.6684 37.0086C58.2037 36.7 58.4714 36.5458 58.6721 36.6617C58.8727 36.7777 58.8727 37.0866 58.8727 37.7045V40.8796C58.8727 41.7856 58.8727 42.2385 58.6572 42.6115C58.4417 42.9844 58.0493 43.2107 57.2644 43.6631L40.2322 53.4811C37.0966 55.2886 35.5288 56.1923 33.8079 56.1915C32.0869 56.1908 30.5199 55.2856 27.386 53.4752L11.4509 44.2702C11.4003 44.2409 11.375 44.2263 11.3514 44.2125C8.01023 42.2601 5.94859 38.6883 5.92925 34.8185C5.92911 34.7912 5.92911 34.762 5.92911 34.7035V31.7889C5.92911 29.6526 7.06688 27.6781 8.91512 26.6068C10.5483 25.6601 12.5628 25.6582 14.1977 26.6019L27.3964 34.2196Z" fill="#4088ff"/>
    </svg>}
  />

  <Card
    title="ReadMe"
    horizontal
    icon={<svg fill="#177fc4" className="h-6 w-6" width="36" height="36" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
    <path d="M29.35 4.361h-7.767c-2.672 0-4.994 1.85-5.578 4.461-0.589-2.611-2.906-4.461-5.578-4.461h-7.761c-1.472 0-2.667 1.194-2.667 2.667v13.656c0 1.472 1.194 2.667 2.667 2.667h4.983c5.678 0 7.372 1.355 8.183 4.167 0.039 0.156 0.289 0.156 0.333 0 0.817-2.811 2.511-4.167 8.183-4.167h4.983c1.472 0 2.667-1.194 2.667-2.667v-13.65c0-1.467-1.183-2.661-2.65-2.672zM13.444 19.105c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 15.722c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.106 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 12.339c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM27.85 19.1c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 15.717c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 12.333c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.267c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.267z"/>
    </svg>}
  />
</CardGroup>

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:

<CodeGroup>
  ```bash Section
  npx @mintlify/scraping@latest section [url]
  ```

  ```bash Page
  npx @mintlify/scraping@latest page [url]
  ```
</CodeGroup>

Global installation:

```
npm install @mintlify/scraping@latest -g
```

Global usage:

<CodeGroup>
  ```bash Section
  mintlify-scrape section [url]
  ```

  ```bash Page
  mintlify-scrape page [url]
  ```
</CodeGroup>

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]
```


# Page Titles and Metadata

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:

<CodeGroup>
  ```md Schema
  ---
  title: "title of the page"
  ---
  ```

  ```md Example
  ---
  title: "Page"
  ---
  ```
</CodeGroup>

<br />

<Tip>
  Mintlify will use the name of the file if you forget to include a title.
</Tip>

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"
---
```

## 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).

<CodeGroup>
  ```md Schema
  api or openapi: method endpoint
  ```

  ```md API Example
  api: "GET /users"
  ```

  ```md OpenAPI Example
  openapi: "GET /users"
  ```
</CodeGroup>

## 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"
---
```

## 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.

### No Mode

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"
---
```

## 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

Start building modern documentation in under five minutes

<Frame>
  <img className="block dark:hidden" src="https://mintlify-assets.b-cdn.net/hero-light.png" />

  <img className="hidden dark:block" src="https://mintlify-assets.b-cdn.net/hero-dark.png" />
</Frame>

## 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.

<AccordionGroup>
  <Accordion icon="github" title="Creating your documentation repository">
    If you've created a docs repo in our onboarding, this step is complete. You can find your docs repository on your Mintlify [dashboard](https://dashboard.mintlify.com).

    To create your docs repo without logging into GitHub, follow these instructions:

    1.  Clone our [starter template](https://github.com/mintlify/starter) into a new public repo. You can make the repo private later.
    2.  [Get in touch](mailto:support@mintlify.com) with our team to deploy your repo.

    <Frame>
      ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png)
    </Frame>
  </Accordion>

  <Accordion icon="message-bot" title="Installing our GitHub app">
    The next step is to install our GitHub app. This ensures 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.

    <Frame>
      ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png)
    </Frame>
  </Accordion>
</AccordionGroup>

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of
your docs.

<AccordionGroup>
  <Accordion icon="rectangle-terminal" title="Editing locally (recommended for developers)">
    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 <your-repo>`. 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).
  </Accordion>

  <Accordion icon="pen-to-square" title="Editing with the web editor">
    Learn more about how to use the web editor on our [guide](/web-editor).
  </Accordion>

  <Accordion icon="palette" title="Customizing to your brand">
    Easily customize colors, logos and buttons among other configurations in our `mint.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).
  </Accordion>

  <Accordion icon="pencil" title="Adding content">
    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).
  </Accordion>

  <Accordion icon="rocket" title="Pushing changes">
    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).

    <Frame>
      ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png)
    </Frame>
  </Accordion>

  <Accordion icon="code-branch" title="Generating API references">
    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 `mint.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 <path-or-url-to-openapi-file>
    ```

    3.  Finally, include the generated endpoint MDX files to your `mint.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).
  </Accordion>

  <Accordion icon="chart-simple" title="Adding analytics">
    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).
  </Accordion>
</AccordionGroup>

<Note>
  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).
</Note>

### Publishing

<Accordion icon="star" title="Adding a custom domain">
  Integrate your docs into your website by hosting them on a custom domain. This is included even in the free plan.

  Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain.

  <Frame>
    ![Custom Domain](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/custom-domain.png)
  </Frame>
</Accordion>

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

Reusable, custom snippets to keep content in sync

One of the core principles of software development is DRY (Don't Repeat
Yourself). This is a principle that applies to documentation as
well. If you find yourself repeating the same content in multiple places, you
should consider creating 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.

<Note>
  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.
</Note>

### Default export

1.  Add content to your snippet file that you want to re-use across multiple
    locations. Optionally, you can add variables that can be filled in via props
    when you import the snippet.

```typescript snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.
```

<Warning>
  The content that you want to reuse must be inside the `snippets` directory in
  order for the import to work.
</Warning>

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.

<MySnippet word="bananas" />
```

### 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 }) => (
  <div>
    <h1>{title}</h1>
    <p>... snippet content ...</p>
  </div>
);
```

<Warning>
  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.
</Warning>

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.

<MyComponent title={'Custom title'} />
```

### 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 <div id="client-component"></div>
  }
}
```


# Editor 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.

<Frame>
  <img className="rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor-gate.png" />
</Frame>

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)

Customize how your team can login to Mintlify

Mintlify supports 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!

<Note>
  SSO functionality is available on our Enterprise plan. [Contact
  us](https://mintlify.com/enterprise) to learn more!
</Note>

## Okta

<Tabs>
  <Tab title="SAML">
    <Steps>
      <Step title="Create an application">
        Under `Applications`, click to create a new app integration using SAML 2.0.
      </Step>

      <Step title="Configure integration">
        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`  |
      </Step>

      <Step title="Send us your IdP information">
        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OIDC">
    <Steps>
      <Step title="Create an application">
        Under `Applications`, click to create a new app integration using OIDC.
        You should choose the `Web Application` application type.
      </Step>

      <Step title="Configure integration">
        Select the authorization code grant type and enter the Redirect URI provided by Mintlify.
      </Step>

      <Step title="Send us your IdP information">
        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. `<your-tenant-name>.okta.com`). You can send these via a service like 1Password or SendSafely.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Google Workspace

<Tabs>
  <Tab title="SAML">
    <Steps>
      <Step title="Create an application">
        Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown.

        <Frame>
          ![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/gsuite-add-custom-saml-app.png)
        </Frame>
      </Step>

      <Step title="Send us your IdP information">
        Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team.

        <Frame>
          ![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/gsuite-saml-metadata.png)
        </Frame>
      </Step>

      <Step title="Configure integration">
        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`

        <Frame>
          ![](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/gsuite-sp-details.png)
        </Frame>

        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!
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Redirects and 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 `mint.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*"
  }
]
```


# Custom Domain

Host the documentation at your website's custom subdomain

To set up your documentation on a custom subdomain, you'll need to set your desired custom subdomain in your Mintlify settings and configure your DNS settings on your domain provider.

<Info>
  Looking to set up a custom subdirectory domain like mintlify.com/docs? Find
  instructions [here](/advanced/subpath/cloudflare).
</Info>

## Dashboard Settings

1.  Head over to your [dashboard project](https://dashboard.mintlify.com)
2.  Click on the "Add custom subdomain".
3.  Enter your desired custom subdomain. For example, `docs.mintlify.com`.

<Frame>
  <img alt="Custom Domain" className="block dark:hidden" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/add-custom-domain-light.png" />

  <img alt="Custom Domain" className="hidden dark:block" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/add-custom-domain-dark.png" />
</Frame>

## 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 subdomain, as well as be emailed to you.

## Configuring your DNS

1.  Proceed to your domain's DNS settings on your domain provider.
2.  Create a new DNS entry, inputting the following values:

```
CNAME | docs | cname.vercel-dns.com.
```

<Frame>
  <img alt="DNS" src="https://mintlify-assets.b-cdn.net/mintlify-dns.png" />
</Frame>

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 subdomain set up after the above configuration.


# GitHub

Sync your docs with a GitHub repo

Mintlify integrates with the GitHub API, enabling synchronization between your
docs and your GitHub repository. This integration is made possible through the
utilization of
[GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps).

## Installation

To begin, you need to install the Mintlify GitHub App into the GitHub account
where your docs repo resides. Installing a GitHub App requires either
organization ownership or admin permissions in a repository. If you lack the
necessary permissions, the repository owner will need to approve the request.
You can access the installation page by logging into the
[Mintlify dashboard](https://dashboard.mintlify.com).

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.

<Frame>
  <img className="h-80" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github/select-repos.png" />
</Frame>

## Permissions

During the installation of our GitHub app, you will be prompted to grant certain
permissions:

*   Read and write access to `checks`, `contents`, `deployments`, `pull requests`,
    and `workflows`

These permissions are leveraged to provide a seamless experience when managing
your docs.

When you make a commit to the branch you configured as your docs deployment
branch, we fetch the contents of the files changed to update your docs. To
accomplish this we need read access to your `contents`.

When pull requests are created we create a check and preview deployment which is
why we need write access to `checks` and `deployments`.

Inside the Mintlify web editor, Mintlify works on your behalf to create branches
and pull requests which is why we need write access to `pull requests` and
`workflows`.

<Info>
  If you are concerned about the write permissions, the GitHub App will only
  have access to the repos you give it access to *and* if you have branch
  protections on it *cannot* push directly to your branches - it abides by your
  branch protection rules.
</Info>

## Repositories Installations

When installing our GitHub app, you will be prompted to select all repositories
or a subset of them. This selection can be changed at any time by going to the
[GitHub app settings](https://github.com/apps/mintlify/installations/new).


# GitLab

Sync your docs with a GitLab repo

<Check>
  GitLab integration is available on the [Enterprise plan](https://mintlify.com/pricing).
</Check>

<Steps>
  <Step title="Find your project ID">
    Navigate to your project's `Settings` > `General` and find the Project ID.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/gitlab/gitlab-project-id.png" />
    </Frame>
  </Step>

  <Step title="Generate a project private token">
    a. Navigate to your project's `Settings` > `Access Tokens`.

    b. Select `Add new token`.

    1.  Name the token "Mintlify" - this specific name is important as it will be visible when we make changes on our end.
    2.  Choose `read_api` for the scopes.
    3.  If you have a private repo, you must set the role as `Reporter`.

    c. Finally click `Create project access token` and copy the token.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/gitlab/gitlab-project-access-token.png" />
    </Frame>
  </Step>

  <Step title="Reach out to the Mintlify team for final setup.">
    Contact us [here](https://mintlify.com/enterprise).
  </Step>
</Steps>


# Global Settings

Customize your documentation using the mint.json file

Every Mintlify site needs a `mint.json` file with the core configuration
settings. Learn more about the [properties](#properties) or from an
[example](#example-mint-json)

## Properties

### Styling

<ResponseField name="name" type="string" required>
  Name of your company or project. Used for the global title.
</ResponseField>

<ResponseField name="logo" type="string or Logo">
  Path to logo image or object with path to "light" and "dark" mode logo images,
  and where the logo links to. SVG format is recommended. It does not pixelate
  and the file size is generally smaller.

  <Expandable title="Logo">
    <ResponseField name="light" type="string">
      Path to the logo in light mode. For example: `/path/to/logo.svg`
    </ResponseField>

    <ResponseField name="dark" type="string">
      Path to the logo in dark mode. For example: `/path/to/logo.svg`
    </ResponseField>

    <ResponseField name="href" type="string" default="/">
      Where clicking on the logo links you to
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="favicon" type="string">
  Path to the favicon image. For example: `/path/to/favicon.svg`
</ResponseField>

<ResponseField name="colors" type="Colors">
  Hex color codes for your global theme

  <Expandable title="Colors">
    <ResponseField name="primary" type="string" required>
      The primary color. Used most often for highlighted content, section
      headers, accents, in light mode
    </ResponseField>

    <ResponseField name="light" type="string">
      The primary color for dark mode. Used most often for highlighted content,
      section headers, accents, in dark mode
    </ResponseField>

    <ResponseField name="dark" type="string">
      The primary color for important buttons
    </ResponseField>

    <ResponseField name="background" type="object">
      The color of the background in both light and dark mode

      <Expandable title="Object">
        <ResponseField name="light" type="string" required>
          The hex color code of the background in light mode
        </ResponseField>

        <ResponseField name="dark" type="string" required>
          The hex color code of the background in dark mode
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="theme" type={'"venus" | "quill" | "prism"'}>
  A preset theme configuration that changes the look and feel of the project. A
  theme is a set of default styling configurations. Examples:
  [Venus](https://starter-venus.mintlify.app),
  [Quill](https://starter-quill.mintlify.app),
  [Prism](https://starter-prism.mintlify.app)
</ResponseField>

<ResponseField name="layout" type={'"topnav" | "sidenav" | "solidSidenav"'} default="topnav">
  The global layout style of the documentation.
</ResponseField>

<ResponseField name="background" type="Background">
  Set a decorative background.

  <Expandable title="Background">
    <ResponseField name="style" type={'"gradient" | "grid" | "windows"'}>
      The style of the decorative background.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="backgroundImage" type="string">
  Set a custom background image to be displayed behind every page.
</ResponseField>

<ResponseField
  name="font"
  type={
   "FontDetailsType | { headings?: FontDetailsType, body?: FontDetailsType }"
  }
>
  Custom fonts. Apply globally or set different fonts for headings and the body
  text.

  Example:

  ```json
  "font": {
    "headings": {
      "family": "Roboto"
    },
    "body": {
      "family": "Oswald"
    }
  }
  ```

  <Expandable title="FontDetailsType">
    <ResponseField name="family" type="string" required>
      The font family name. Custom fonts and all [Google
      Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans",
      "Playfair Display"
    </ResponseField>

    <ResponseField name="weight" type="number">
      The font weight. Precise values such as `560` are also supported for
      variable fonts. Check under the Styles section for your Google Font for
      the available weights.
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL to the font file. Can be used to specify a font that is not from
      Google Fonts.
    </ResponseField>

    <ResponseField name="format" type="'woff' | 'woff2'">
      The font format. Required if using a custom font source (`url`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="modeToggle" type="ModeToggle">
  Customize the dark mode toggle.

  <Expandable title="ModeToggle">
    <ResponseField name="default" type={'"light" or "dark"'}>
      Set if you always want to show light or dark mode for new users. When not
      set, we default to the same mode as the user's operating system.
    </ResponseField>

    <ResponseField name="isHidden" type="boolean" default={false}>
      Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:

      <CodeGroup>
        ```json Only Dark Mode
        "modeToggle": {
          "default": "dark",
          "isHidden": true
        }
        ```

        ```json Only Light Mode
        "modeToggle": {
          "default": "light",
          "isHidden": true
        }
        ```
      </CodeGroup>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sidebar" type="Sidebar">
  Customize the styling of components within the sidebar.

  <Expandable title="Sidebar">
    <ResponseField name="items" type={'"container" | "card" | "border" | "undecorated"'} default="container">
      The styling of the navigation item.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topbar" type="Topbar">
  Styling configurations for the topbar.

  <Expandable title="Topbar">
    <ResponseField name="style" type={'"default" | "gradient"'} default="default">
      The styling of the navigation item.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="Search">
  The location options for the search bar.

  <Expandable title="Search">
    <ResponseField name="location" type={'"side" | "top"'}>
      The location of the search bar.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rounded" type={'"default" | "sharp"'}>
  The style of the rounded edges.
</ResponseField>

<ResponseField name="codeBlock" type="CodeBlock">
  The style of the code block.

  <Expandable title="CodeBlock">
    <ResponseField name="mode" type={'"dark" | "auto"'} default="dark">
      `auto` will automatically switch between light and dark mode based on the
      user's system preferences.
    </ResponseField>
  </Expandable>
</ResponseField>

### Structure

<ResponseField name="navigation" type="Navigation[]" required>
  An array of groups with all the pages within that group

  <Expandable title="Navigation">
    <ResponseField name="group" type="string">
      The name of the group.
    </ResponseField>

    <ResponseField name="pages" type="string[]">
      The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.
    </ResponseField>

    <ResponseField name="icon" type="string">
      The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders.
    </ResponseField>

    <ResponseField name="iconType" type="string">
      The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topbarLinks" type="TopbarLink[]">
  Array of names and urls of links you want to include in the topbar

  <Expandable title="TopbarLink">
    <ResponseField name="name" type="string">
      The name of the button.
    </ResponseField>

    <ResponseField name="url" type="string">
      The url once you click on the button. Example: `https://mintlify.com/contact`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topbarCtaButton" type="Call to Action">
  <Expandable title="Topbar Call to Action">
    <ResponseField name="type" type={"link or github"} default="link">
      Link shows a button. GitHub shows the repo information at the url provided
      including the number of GitHub stars.
    </ResponseField>

    <ResponseField name="url" type="string">
      If type is a link: What the button links to. If type is a github: Link to
      the repository to load GitHub information from.
    </ResponseField>

    <ResponseField name="name" type="string">
      Text inside the button. Only required if type is a link.
    </ResponseField>

    <ResponseField name="style" type={'"pill" | "roundedRectangle"'}>
      The style of the button.
    </ResponseField>

    <ResponseField name="arrow" type="boolean">
      Whether to display the arrow
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="versions" type="string[]">
  Array of version names. Only use this if you want to show different versions
  of docs with a dropdown in the navigation bar.

  Versions can be leveraged for localization. You can store translated content
  under a version, and once you specify the `locale` any fixed text in Mintlify,
  such as 'Was this page helpful?', will automatically be translated based on the
  locale. We currently support localization in English, Chinese, Spanish, French,
  Japanese, and Portuguese.

  For more information, please refer to our
  [versioning documentation](/settings/versioning).

  Example:

  <CodeGroup>
    ```json Default
    "versions": ["v1.0", "v1.1"]
    ```

    ```json Localization
    "versions": [
      {
        "name": "English",
        "locale": "en",
      },
      {
        "name": "Español",
        "locale": "es"
      }
    ]
    ```
  </CodeGroup>

  <Expandable title="Version">
    <ResponseField name="name" type="string" required>
      The version name.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`.
    </ResponseField>

    <ResponseField name="default" type="true">
      Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="anchors" type="Anchor[]">
  An array of the anchors, includes the icon, color, and url.

  <img className="block h-32 dark:hidden" src="https://mintlify-assets.b-cdn.net/anchors-light.png" />

  <img className="hidden h-32 dark:block" src="https://mintlify-assets.b-cdn.net/anchors-dark.png" />

  <Expandable title="Anchor">
    <ResponseField name="name" type="string" required>
      The name of the anchor label.

      Example: `Community`
    </ResponseField>

    <ResponseField name="icon" type="string">
      The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.

      Example: `comments`
    </ResponseField>

    <ResponseField name="url" type="string">
      The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
    </ResponseField>

    <ResponseField name="color" type="string">
      The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
    </ResponseField>

    <ResponseField name="version" type="string">
      Used if you want to hide an anchor until the correct docs version is selected.
    </ResponseField>

    <ResponseField name="isDefaultHidden" type="boolean" default={false}>
      Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
    </ResponseField>

    <ResponseField name="iconType" default="duotone" type="string">
      One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topAnchor" type="Anchor">
  Override the default configurations for the top-most anchor. Note: if you have
  tabs configured, this does not apply.

  <Expandable title="Anchor">
    <ResponseField name="name" default="Documentation" type="string" required>
      The name of the top-most anchor
    </ResponseField>

    <ResponseField name="icon" default="book-open" type="string">
      Font Awesome icon.
    </ResponseField>

    <ResponseField name="iconType" default="duotone" type="string">
      One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tabs" type="Tabs[]">
  An array of navigational tabs.

  Example:

  ```json
  "tabs": [
    {
      "name": "Writing Content",
      "url": "content"
    },
    {
      "name": "API References",
      "url": "api-playground"
    }
  ]
  ```

  <Expandable title="Tabs">
    <ResponseField name="name" type="string">
      The name of the tab label.
    </ResponseField>

    <ResponseField name="url" type="string">
      The start of the URL that marks what pages go in the tab. Generally, this
      is the name of the folder you put your pages in.
    </ResponseField>

    <ResponseField name="isDefaultHidden" type="boolean" default={false}>
      Pass `true` if you want to hide the tab until you directly link someone to docs inside it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="footer" type="{ socials?: FooterSocials, links?: FooterLinksColumn[] }">
  An object to configure the footer with socials and links.
  Example:

  ```json
  "footer": {
    "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
    "links": [
      {
        "title": "Column 1",
        "links": [
          { "label": "Column 1 Link 1", "url": "https://mintlify.com" }, 
          { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
        ]
      }, 
      {
        "title": "Column 2",
        "links": [
          { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
          { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
        ]
      }
    ]
  }
  ```

  <Expandable title="FooterSocials">
    <ResponseField name="[key]" type="string">
      One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`

      Example: `x`
    </ResponseField>

    <ResponseField name="value" type="string">
      The URL to the social platform.

      Example: `https://x.com/mintlify`
    </ResponseField>
  </Expandable>

  <Expandable title="FooterLinksColumn">
    <ResponseField name="title" type="string">
      Title of the column
    </ResponseField>

    <ResponseField name="links" type="{ label: string, url: string }[]">
      The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="feedback" type="Feedback">
  Configurations to enable feedback buttons

  <Expandable title="Feedback">
    <ResponseField name="thumbsRating" type="boolean" default={false}>
      Enables a rating system for users to indicate whether the page has been helpful
    </ResponseField>

    <ResponseField name="suggestEdit" type="boolean" default={false}>
      Enables a button to allow users to suggest edits via pull requests
    </ResponseField>

    <ResponseField name="raiseIssue" type="boolean" default={false}>
      Enables a button to allow users to raise an issue about the documentation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="Search">
  Configurations to change the search prompt

  <Expandable title="Search">
    <ResponseField name="prompt" type="string" default="undefined">
      Set the prompt for the search bar. Default is `Search...`
    </ResponseField>
  </Expandable>
</ResponseField>

### API Configurations

<ResponseField name="api" type="API">
  Configuration for API settings. Learn more about API pages at [API Components](/api-playground).

  <Expandable title="API">
    <ResponseField name="baseUrl" type="string">
      The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
      options that the user can toggle.
    </ResponseField>

    <ResponseField name="auth" type="Auth">
      <Expandable title="Auth">
        <ResponseField name="method" type="&#x22;bearer&#x22; | &#x22;basic&#x22; | &#x22;key&#x22;">
          The authentication strategy used for all API endpoints.
        </ResponseField>

        <ResponseField name="name" type="string">
          The name of the authentication parameter used in the API playground.

          If method is `basic`, the format should be `[usernameName]:[passwordName]`
        </ResponseField>

        <ResponseField name="inputPrefix" type="string">
          The default value that's designed to be a prefix for the authentication input field.

          E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="playground" type="Playground">
      Configurations for the API playground

      <Expandable title="Playground">
        <ResponseField name="mode" default="show" type="&#x22;show&#x22; | &#x22;simple&#x22; | &#x22;hide&#x22;">
          Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`

          Learn more at the [playground guides](/api-playground)
        </ResponseField>

        <ResponseField name="disableProxy" type="boolean" default={false}>
          By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.

          Required for select request types, such as file uploads.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="request" type="object">
      Configurations for API requests

      <Expandable title="Request">
        <ResponseField name="example" type="object">
          Configurations for the auto-generated API request examples

          <Expandable>
            <ResponseField name="languages" type="string[]">
              An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java`
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="paramFields" type="ApiParamFields">
      Configurations for the param fields in the API Playground

      <Expandable title="ApiParamFields">
        <ResponseField name="expanded" default="none" type="&#x22;all&#x22; | &#x22;topLevel&#x22; | &#x22;topLevelOneOfs&#x22; | &#x22;none&#x22;">
          The default expanded state of expandable options in the API playground.

          `"all"` - every expandable component is expanded

          `"topLevel"` - every top-level expandable component is expanded

          `"topLevelOneOfs"` - every top-level `oneOf` type is expanded

          `"none"` - every expandable component is closed (default behavior)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="openapi" type="string | string[]">
  A string or an array of strings of URL(s) or relative path(s) pointing to your
  OpenAPI file.

  Examples:

  <CodeGroup>
    ```json Absolute
    "openapi": "https://example.com/openapi.json"
    ```

    ```json Relative
    "openapi": "/openapi.json"
    ```

    ```json Multiple
    "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
    ```
  </CodeGroup>
</ResponseField>

### Integrations

<ResponseField name="integrations" type="Integrations">
  Configurations to add third-party integrations (excluding analytics integrations)

  <Expandable title="Integrations">
    <ResponseField name="intercom" type="string">
      Enables Intercom widget on docs site. The value should be your Intercom App ID.
    </ResponseField>

    <ResponseField name="frontchat" type="string">
      Enables Frontchat widget on docs site. The value should be your Frontchat App ID.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="analytics" type="Analytics">
  Configurations to add third-party analytics integrations. See full list of
  supported analytics [here](/integrations/analytics/overview).
</ResponseField>

### Redirects

<ResponseField name="redirects" type="Redirect[]">
  An array of paths you want to configure to permanently redirect to another path

  Example:

  ```json
  "redirects": [
    {
      "source": "/source/path",
      "destination": "/destination/path"
    }
  ]
  ```

  <Expandable title="Redirect">
    <ResponseField name="source" type="string">
      The path that you want to redirect from.

      Example: `/source`
    </ResponseField>

    <ResponseField name="destination" type="string">
      The path that you want to redirect to.

      Example: `/destination`
    </ResponseField>
  </Expandable>
</ResponseField>

### Search Engine Optimization

<ResponseField name="seo" type="SEO">
  Settings for Search Engine Optimization.

  Example:

  ```json
  "seo": {
    "indexHiddenPages": true
  }
  ```

  <Expandable title="Redirect">
    <ResponseField name="indexHiddenPages" type="boolean" default="false">
      Enables indexing pages not included in `navigation`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example `mint.json`

Click on the following dropdown to view a sample configuration file

<Accordion title="View Example Configuration">
  ```json
  {
    "name": "Mintlify",
    "logo": {
      "light": "/logo/light.svg",
      "dark": "/logo/dark.svg"
    },
    "favicon": "/favicon.svg",
    "colors": {
      "primary": "#16A34A",
      "light": "#4ADE80",
      "dark": "#166534"
    },
    "topbarLinks": [
      {
        "name": "Contact Us",
        "url": "mailto:support@mintlify.com"
      }
    ],
    "topbarCtaButton": {
      "name": "Get Started",
      "url": "https://1tc7vihvbit.typeform.com/to/pZJ31XZB"
    },
    "anchors": [
      {
        "name": "API Components",
        "icon": "rectangle-terminal",
        "color": "#f59f0b",
        "url": "api-components"
      },
      {
        "name": "Community",
        "icon": "comments",
        "color": "#2564eb",
        "url": "https://discord.gg/MPNgtSZkgK"
      }
    ],
    "navigation": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      },
      {
        "group": "API Components",
        "pages": ["api-playground/overview", "api-playground/configuration"]
      },
      {
        "group": "Settings",
        "pages": ["settings/global", "settings/page"]
      },
      {
        "group": "Analytics",
        "pages": ["analytics/posthog"]
      }
    ],
    "footerSocials": {
      "github": "https://github.com/mintlify",
      "slack": "https://mintlify.com/community",
      "x": "https://x.com/mintlify"
    },
    "integrations": {
      "intercom": "APP_ID",
      "frontchat": "CHAT_ID"
    }
  }
  ```
</Accordion>

## More Customization

Learn more about how to further customize your docs with custom CSS and JS in
[Custom Scripts](https://mintlify.com/docs/advanced/custom/).


# Navigation

Organize your docs directory to guide your users to the information they need 

## Tabs

Tabs help distinguish between different topics or sections of your
documentation. They show up above the main sidebar.

<Frame>
  <img className="block dark:hidden rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/tabs-light.png" />

  <img className="hidden dark:block rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/tabs-dark.png" />
</Frame>

Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of
the tab object should map to a folder of content added to your sidebar, or an
external link.

```json
"tabs": [
    {
        "name": "API References",
        "url": "api-references"
    },
    {
        "name": "Content",
        "url": "content"
    },
    {
        "name": "Blog",
        "url": "https://your-website.com/blog"
    }
]
```

To configure the default `Documentation` primary tab, add the `primaryTab` field
to your `mint.json` file with your desired name. Any files in your navigation
not in a folder reserved by another tab will show up in the primary tab.

```json
"primaryTab": {
    "name": "Home"
}
```

## Anchors

Anchors provide another way to direct users to sections of your documentation,
or link out to external URLs.

<Frame>
  <img className="block dark:hidden rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/anchor-light.png" />

  <img className="hidden dark:block rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/anchor-dark.png" />
</Frame>

Configure anchors with the `anchors` field of the `mint.json` file. The `url`
field of the tab object should map an external link, or a folder of content
added to your sidebar. More fields for anchors can be found
[here](/settings/global).

```json
"anchors": [
    {
        "name": "API References",
        "icon": "code",
        "url": "api-references"
    },
    {
        "name": "Content",
        "icon": "pencil",
        "url": "content"
    },
    {
        "name": "Contact us",
        "icon": "envelope",
        "url": "https://mintlify.com/contact-us"
    }
]
```

To configure the default `Documentation` top anchor, add the `topAnchor` field
to your `mint.json`.

```json
"topAnchor": {
    "name": "Home",
    "icon": "building"
}
```

## Sidebar

Organize your navigation by defining the `navigation` property in your
mint.json, You don't need to include `.mdx` in page names.

<Info>
  Once you add a page to your docs directory, you'll need to add the path to
  `mint.json` to add it to the sidebar. Pages do not show up automatically.
</Info>

```json Regular Navigation
"navigation": [
    {
        "group": "Getting Started",
        "pages": ["quickstart"]
    }
]
```

### Groups

Create groups by recursively nesting a group within a group.

```json Nested Navigation
"navigation": [
    {
        "group": "Getting Started",
        "pages": [
            "quickstart",
            {
                "group": "Nested Reference Pages",
                "pages": ["nested-reference-page"]
            }
        ]
    }
]
```

### Folders

Simply put your MDX files in folders and update the paths in `mint.json`.

For example, to have a page at `https://yoursite.com/your-folder/your-page` you
would make a folder called `your-folder` containing an MDX file called
`your-page.mdx`.

<Warning>
  You cannot use `api` for the name of a folder unless you nest it inside
  another folder. Mintlify uses Next.js which reserves the top-level `api`
  folder for internal server calls. We recommend using the folder name
  `api-reference` instead.
</Warning>

<CodeGroup>
  ```json Navigation With Folder
  "navigation": [
      {
          "group": "Group Name",
          "pages": ["your-folder/your-page"]
      }
  ]
  ```

  ```json Nested Navigation
  "navigation": [
      {
          "group": "Getting Started",
          "pages": [
              "quickstart",
              {
                  "group": "Nested Reference Pages",
                  "pages": ["nested-reference-page"]
              }
          ]
      }
  ]
  ```
</CodeGroup>

### Hidden Pages

MDX files not included in `mint.json` will not show up in the sidebar but are
accessible by linking directly to them.

Hidden pages are not indexed for search within your docs by default. If you
would like to override this behavior, you can set the
[`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute
in your `mint.json` to `true`.

## Topbar

### Links

Add links to the topbar with the `topbarLinks` field in the `mint.json` file.

<Frame>
  <img className="block rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/topbar-links.png" />
</Frame>

The `topbarLinks` field supports the following fields: `name`, `url`.

```json
  "topbarLinks": [
    {
      "name": "Community",
      "url": "https://mintlify.com/community"
    }
  ]
```

### CTA Button

Customize the call-to-action (CTA) button in the topbar using the `topbarCTA`
field.

<Frame>
  <img className="block rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/topbar-cta-get-started.png" />
</Frame>

The `topbarCTA` field supports the following fields: `name`, `url`, and `type`.

```json
  "topbarCTA": {
    "name": "Get Started",
    "url": "https://mintlify.com/get-started"
  }
```

#### GitHub

You can also configure the CTA button to link directly to your GitHub
repository. Use the `topbarCtaButton` field with the `type` set to `github`.

<Frame>
  <img className="block rounded-md" src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/topbar-cta-github.png" />
</Frame>

```json
  "topbarCtaButton": {
    "type": "github",
    "url": "https://github.com/mintlify/docs"
  }
```


# Search Engine Optimization

Mintlify automatically generates most meta tags. If you want to customize them, you can set default values in mint.json or change them per page.

<Accordion title="Supported Meta Tags">
  *   og:site\_name
  *   og:title
  *   og:description
  *   og:url
  *   og:image
  *   og:locale
  *   og:logo
  *   article:publisher
  *   twitter:title
  *   twitter:description
  *   twitter:url
  *   twitter:image
  *   twitter:site
  *   og:image:width
  *   og:image:height
</Accordion>

## Default meta tags

You can set default meta tags by adding the `metadata` field to your `mint.json`.

```json
"metadata": {
    "og:image": "link to your default meta tag image"
}
```

## Changing meta tags on one page

Add your meta tags to the page's metadata like so:

```md
---
title: 'Your Example Page Title'
'og:image': 'link to your meta tag image'
---
```

<Warning>
  Meta tags with colons need to be typed with quotes around them when you put them in the page metadata.
</Warning>

## Sitemaps

Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. Simply add `/sitemap.xml` to the end of your website URL to see your sitemap. We recommend submitting the sitemap to search engines for improved SEO.

Only pages included in your `mint.json` are included by default. To include hidden links, add `seo.indexHiddenPages` to your `mint.json`:

```json
"seo": {
    "indexHiddenPages": true
}
```

## Disabling indexing

If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/page) of your page:

```
---
noindex: true
---
```


# Versioning

Build separate versions

These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized.

## Setup

Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version.

<Tip>
  The versions dropdown will show your versions in the order you include them in
  `mint.json`.
</Tip>

## Versioning Groups and Pages

The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group.

You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence.

<CodeGroup>
  ```json Groups (mint.json)
  "navigation": [
    {
      "group": "Getting Started",
      "version": "v1",
      "pages": [...]
    }
  ],
  ```

  ```yaml Pages (quickstart.mdx)
  ---
  title: 'Quickstart'
  version: 'v2'
  ---
  ```
</CodeGroup>

<Warning>
  While it is possible to nest versioned groups within versioned groups, it is not recommended. If you do take this approach, the more deeply-nested version takes precedence.
</Warning>

### Versioning Tabs and Anchors

You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor.

In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version.

<CodeGroup>
  ```json Tabs
  "tabs": [
    {
      "name": "API Reference V1",
      "url": "v1/api-reference",
      "version": "v1"
    },
    {
      "name": "API Reference V2",
      "url": "v2/api-reference",
      "version": "v2"
    },
    {
      "name": "Migrating from V1 to V2",
      "url": "https://mintlify.com/changelog/v2"
    },
  ],
  ```

  ```json Anchors
  "anchors": [
    {
      "name": "API Reference V1",
      "url": "v1/api-reference",
      "version": "v1"
    },
    {
      "name": "API Reference V2",
      "url": "v2/api-reference",
      "version": "v2"
    },
    {
      "name": "Migrating from V1 to V2",
      "url": "https://mintlify.com/changelog/v2",
      "version": "v2"
    },
  ],
  ```
</CodeGroup>

### Sharing Between Versions

Not *all* content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content!

## Troubleshooting

Common errors and how to fix them

<AccordionGroup>
  <Accordion title="Pages Show Up In Wrong Version" icon="circle-exclamation">
    You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2".

    We do not recommend nesting versions inside of each other because it's hard to maintain your docs later.
  </Accordion>

  <Accordion title="Missing Pages" icon="circle-exclamation">
    If you add versions to your docs and the pages disappeared from your
    navigation, make sure you spelled the version the same as in your `versions`
    array in `mint.json`.
  </Accordion>
</AccordionGroup>


# Headers and Text

Text, title, and styling in standard markdown

## Titles

Best used for section headers.

```md
## Titles
```

### Subtitles

Best use to subsection headers.

```md
### Subtitles
```

<Tip>
  Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
</Tip>

## Text Formatting

We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.

| Style         | How to write it   | Result            |
| ------------- | ----------------- | ----------------- |
| Bold          | `**bold**`        | **bold**          |
| Italic        | `_italic_`        | *italic*          |
| Strikethrough | `~strikethrough~` | ~~strikethrough~~ |

You can combine these. For example, write `**_bold and italic_**` to get ***bold and italic*** text.

You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.

| Text Size   | How to write it          | Result                 |
| ----------- | ------------------------ | ---------------------- |
| Superscript | `<sup>superscript</sup>` | <sup>superscript</sup> |
| Subscript   | `<sub>subscript</sub>`   | <sub>subscript</sub>   |

## Linking to Pages

You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).

Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page "Text" in our components section.

Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.

You can validate broken links in your docs with [our CLI](/development).

## Blockquotes

### Singleline

To create a blockquote, add a `>` in front of a paragraph.

> Dorothy followed her through many of the beautiful rooms in her castle.

```md
> Dorothy followed her through many of the beautiful rooms in her castle.
```

### Multiline

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

```md
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```

### LaTeX

Mintlify supports in-line [LaTeX](https://www.latex-project.org) by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$.

Equations on their own line can be created with double dollar signs (\$\$):

$\exists \, x \notin [0,1]$

```md
$$\exists \, x \notin [0,1]$$
```

### Line Breaks

Markdown syntax also recognizes a double enter in your MDX as a linebreak.

```html
<br />
```

```md
Paragraph 1

Paragraph 2
```


# Web Editor

Edit your docs directly from the dashboard with live previews.

<Warning>
  Mintlify Web Editor is currently in beta. We are in the process of adding additional
  features and fixing bugs. We'd love to get your feedback on what we can improve at [support@mintlify.com](mailto:support@mintlify.com).
</Warning>

Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`.

The editor includes a few key features to integrate directly into your existing git workflow,
like creating branches, pull requests, commits, and diffs for your current changes.

It also includes a fully editable experience for changing and adding content directly,
even with custom components.

If you understand git workflows and our integrations already, you can skip to [here](#editing-content).

## Git and update workflows

### Git basics

While Web Editor means you don’t need to go to GitHub or your command line to make
changes, it’s still helpful to know the basics of git.

Git terminology:

*   **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub).

*   **Commit**: A snapshot of changes made to files in the repository.

*   **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version.

*   **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live.

### Making updates

In order to make updates to your docs, we include a few buttons specifically to
integrate with your git workflow.

<Note>
  If you haven't done so already, please install the Mintlify GitHub app to your GitHub account.
  You can find [documentation here](#1-deploying-your-docs-repository), or you can install
  the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app)
  page of the dashboard.
</Note>

<Steps>
  <Step title="Creating new branches">
    In order to make changes to your docs, you might want to change from the main branch
    to avoid publishing directly to your main docs site.

    To do this, you can open the branches modal on the top left of the editor.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/branches-light.png" className="block dark:hidden" />

      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/branches-dark.png" className="hidden dark:block" />
    </Frame>

    From here, you can either switch to a different git branch than `main`, or you can
    create a new branch by clicking the **"New Branch"** button.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/new-branch-light.png" className="block dark:hidden" />

      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/new-branch-dark.png" className="hidden dark:block" />
    </Frame>

    After you create a new branch, you'll automatically be switched, and all changes
    you make will be made to this new branch until you change branches again or reload the page.

    By default, when you load the page again, you'll default to the main branch.

    <Tip>
      As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you.
    </Tip>
  </Step>

  <Step title="Making a commit">
    In order to make a commit, you have two options, both of which appear on the top
    right of the editor:

    <Tabs>
      <Tab title="Main branch">
        If you're on the main branch of your docs repository, you can push a commit
        directly to the repo by clicking the **"Publish"** button. You'll see your changes
        reflect in your git branch the next time you run `git pull`.

        <Frame>
          <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/publish-button-light.png" className="block dark:hidden" />

          <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/publish-button-dark.png" className="hidden dark:block" />
        </Frame>
      </Tab>

      <Tab title="Different branch">
        If you're not on the main branch, you can push a commit to your branch by clicking
        on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch
        up for review, you can click the **"Publish Pull Request"** button.

        <Frame>
          <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/pull-request-button-light.png" className="block dark:hidden" />

          <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/pull-request-button-dark.png" className="hidden dark:block" />
        </Frame>
      </Tab>
    </Tabs>

    This will create the pull request for you on GitHub using the branch you selected onto
    your main branch.
  </Step>

  <Step title="Making a pull request">
    If you do put your pull request up for review, you can edit the title and description
    of the PR, but a default Mintlify title will be provided for you if you leave it
    empty.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/pr-modal-light.png" className="block dark:hidden" />

      <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/pr-modal-dark.png" className="hidden dark:block" />
    </Frame>
  </Step>
</Steps>

## Editing content

### Slash commands

The easiest way to add content in the editor is by using **"Slash commands"**, which are
commands you have access to after typing `/` in the **"Visual Editor"** mode:

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/slash-commands-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/slash-commands-dark.png" className="hidden dark:block" />
</Frame>

As you type, you'll see more options pop up:

<Frame caption="Command filtering">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/slash-commands-text-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/slash-commands-text-dark.png" className="hidden dark:block" />
</Frame>

#### Content blocks

Here are the types of content blocks available to add in the **"Visual Editor"**:

<AccordionGroup>
  <Accordion title="Standard markdown blocks">
    <CardGroup cols={2}>
      <Card icon="paragraph" href="/text#text-formatting" horizontal>Paragraph</Card>
      <Card icon="heading" href="/text#titles" horizontal>Headings</Card>
      <Card icon="list-ul" href="/list-table#unordered-list" horizontal>Bullet List</Card>
      <Card icon="list-ol" href="/list-table#ordered-list" horizontal>Numbered List</Card>
      <Card icon="table" href="/list-table#tables" horizontal>Table</Card>
      <Card icon="image" href="/image-embeds" horizontal>Image</Card>
      <Card icon="block-quote" href="/text#blockquotes" horizontal>Blockquote</Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Mintlify components">
    <CardGroup cols={2}>
      <Card icon="circle-exclamation" href="/content/components/callouts" horizontal>Callouts</Card>
      <Card icon="square-caret-down" href="/content/components/accordions" horizontal>Accordions</Card>
      <Card icon="table-rows" href="/content/components/accordion-groups" horizontal>Accordion Group</Card>
      <Card icon="rectangle" href="/content/components/cards" horizontal>Cards</Card>
      <Card icon="rectangles-mixed" href="/content/components/card-groups" horizontal>Card Group</Card>
      <Card icon="code" href="/content/components/code" horizontal>Code Block</Card>
      <Card icon="rectangle-code" href="/content/components/code-groups" horizontal>Code Group</Card>
      <Card icon="window-restore" href="/content/components/tabs" horizontal>Tabs</Card>
      <Card icon="arrow-progress" href="/content/components/steps" horizontal>Steps</Card>
      <Card icon="frame" href="/content/components/frames" horizontal>Frames</Card>
      <Card icon="rectangle-history" href="/content/components/update" horizontal>Update</Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

### Adding images

You can add images to your page by typing `/image` and either clicking on the **"Image"**
option or hitting <kbd>↓</kbd> + <kbd>Enter</kbd> on the **"Image"** option.

This will open up the image modal where you have the option to either upload a new
image or use an existing image from the repo.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/images-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/images-dark.png" className="hidden dark:block" />
</Frame>

Uploading an image can be done through the modal:

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/upload-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/upload-dark.png" className="hidden dark:block" />
</Frame>

And you can preview an existing image before you add it.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/image-preview-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/image-preview-dark.png" className="hidden dark:block" />
</Frame>

### Editing images

In order to edit images, you just have to hover over the image to see the **"Delete"**
and **"Edit"** buttons on the top right of the image.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/edit-image-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/edit-image-dark.png" className="hidden dark:block" />
</Frame>

Clicking the **"Edit"** button lets you edit the attributes of the image.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/image-form-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/image-form-dark.png" className="hidden dark:block" />
</Frame>

If you want to update the source of an image to be a new image that you haven't yet
uploaded, you have to first delete the image you're changing, and then add a new one
using the [instructions above](#adding-images).

## Editor modes

In order to offer the most flexibility, the editor has three modes:

<Frame caption="View mode toggle">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/mode-toggle-light.png" className="block dark:hidden" />

  <img src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/editor/mode-toggle-dark.png" className="hidden dark:block" />
</Frame>

### Visual Editor

The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion.
It offers you a view into your docs in a fully editable way that reflects what the final
page would look like on your main docs site.

### Source Editor

The **"Source Editor"** offers you a way to edit your MDX files in code, the same way
you'd do in your IDE. This offers less flexibility, in that our components aren't available
for auto-complete, but it does have two unique advantages.

1.  It allows you to edit props of components (see our [limitations below](#current-limitations))
    which is currently not available in **"Visual Editor"** mode yet.

2.  It allows you to correct syntax errors which might've appeared in your repo that
    might not be compatible with **"Visual Editor"** mode until you've fixed them.

### Diff View

The **"Diff View"** is a way to view the changes made to a specific document before
committing it to your repository.

This will help you see changes you've made along with formatting changes made by
the editor.

## Current limitations

We do have a few current limitations in the editor that we're working to resolve.

<AccordionGroup>
  <Accordion title="Editing the props of components">
    In components like `<Card>` and `<Accordion>` which have props like title, icon,
    href, etc., you currently cannot edit those props without going to the **"Source Editor"**
  </Accordion>

  <Accordion title="WYSIWYG navigation tree">
    You currently cannot live-update your navigation based on added/edited files. You
    still have to manually edit renamed, added, and deleted files in your `mint.json`
  </Accordion>

  <Accordion title="Snippet previews">
    We currently don't show any previews for custom snippets. This is on our roadmap to support
    as fully editable components.
  </Accordion>

  <Accordion title="OpenAPI previews">
    We currently don't show any previews for OpenAPI specs. This is on our roadmap to support
    as a read-only preview.
  </Accordion>

  <Accordion title="Keyboard navigation">
    There are currently some bugs around keyboard navigation that we're working to resolve.
    This includes things like going back/forward and up/down between Mintlify components and normal
    markdown blocks, or deleting a line vs. a Mintlify component.
  </Accordion>
</AccordionGroup>

## Feedback

If you have any bug reports, feature requests, or other general feedback, we'd love to hear
where we can improve.

Email us at [support@mintlify.com](mailto:support@mintlify.com)