# Source: https://www.mintlify.com/docs/organize/settings.md

> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Global settings

> Configure site-wide settings in docs.json.

The `docs.json` file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. Think of it as the blueprint for your documentation.

Settings in `docs.json` apply globally to all pages.

## Setting up your `docs.json`

To get started, you only need to specify `theme`, `name`, `colors.primary`, and `navigation`. Other fields are optional and you can add them as your documentation needs grow.

For the best editing experience, include the schema reference at the top of your `docs.json` file. This enables autocomplete, validation, and helpful tooltips in most code editors:

```json  theme={null}
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your Docs",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // Your navigation structure
  }
  // The rest of your configuration
}
```

## Reference

This section contains the full reference for the `docs.json` file.

### Customization

<ResponseField name="theme" required>
  The layout theme of your site.

  One of the following: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`.

  See [Themes](/customize/themes) for more information.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of your project, organization, or product.
</ResponseField>

<ResponseField name="colors" type="object" required>
  The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it applies to all color elements.

  <Expandable title="Colors">
    <ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
      The primary color for your documentation. Generally used for emphasis in light mode, with some variation by theme.

      Must be a hex code beginning with `#`.
    </ResponseField>

    <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
      The color used for emphasis in dark mode.

      Must be a hex code beginning with `#`.
    </ResponseField>

    <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
      The color used for buttons and hover states across both light and dark modes, with some variation by theme.

      Must be a hex code beginning with `#`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string">
  Description of your site for SEO and AI indexing.
</ResponseField>

<ResponseField name="logo" type="string or object">
  Set your logo for both light and dark mode.

  <Expandable title="Logo">
    <ResponseField name="light" type="string" required>
      Path pointing to your logo file for light mode. Include the file extension. Example: `/logo.png`
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      Path pointing to your logo file for dark mode. Include the file extension. Example: `/logo-dark.png`
    </ResponseField>

    <ResponseField name="href" type="string (uri)">
      The URL to redirect to when clicking the logo. If not provided, the logo links to your homepage. Example: `https://mintlify.com`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="favicon" type="string or object">
  Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. Can be a single file or separate files for light and dark mode. Example: `/favicon.png`

  <Expandable title="Favicon">
    <ResponseField name="light" type="string" required>
      Path to your favicon file for light mode. Include the file extension. Example: `/favicon.png`
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      Path to your favicon file for dark mode. Include the file extension. Example: `/favicon-dark.png`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thumbnails" type="object">
  Thumbnail customization for social media and page previews.

  <Expandable title="Thumbnails">
    <ResponseField name="appearance" type="&#x22;light&#x22; | &#x22;dark&#x22;">
      The visual theme of your thumbnails. If not specified, thumbnails use your site's color scheme defined by the `colors` field.
    </ResponseField>

    <ResponseField name="background" type="string">
      Background image for your thumbnails. Can be a relative path or absolute URL.
    </ResponseField>

    <ResponseField name="fonts" type="object">
      Font configuration for thumbnails. Only supports Google Fonts family names.

      <Expandable title="Fonts">
        <ResponseField name="family" type="string" required>
          Font family name, such as "Open Sans" or "Playfair Display". Supports [Google Fonts](https://fonts.google.com) family names.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="styling" type="object">
  Visual styling configurations.

  <Expandable title="Styling">
    <ResponseField name="eyebrows" type="&#x22;section&#x22; | &#x22;breadcrumbs&#x22;">
      The style of the page eyebrow. Choose `section` to show the section name or `breadcrumbs` to show the full navigation path. Defaults to `section`.
    </ResponseField>

    <ResponseField name="latex" type="boolean">
      Controls whether LaTeX stylesheets are included, overriding automatic detection. By default, Mintlify automatically detects LaTeX usage in your content and loads the necessary stylesheets.

      * Set to `true` to force-load LaTeX stylesheets when automatic detection fails to recognize your mathematical expressions.
      * Set to `false` to prevent loading LaTeX stylesheets for improved performance if you don't use mathematical expressions but have content that triggers false-positive detection.
    </ResponseField>

    <ResponseField name="codeblocks" type="&#x22;system&#x22; | &#x22;dark&#x22; | string | object">
      Code block theme configuration. Defaults to `"system"`.

      **Simple configuration:**

      * `"system"`: Match current site mode (light or dark)
      * `"dark"`: Always use dark mode

      **Custom theme configuration:**

      * Use a string to specify a single [Shiki theme](https://shiki.style/themes) for all code blocks
      * Use an object to specify separate [Shiki themes](https://shiki.style/themes) for light and dark modes

      <ResponseField name="theme" type="string">
        A single Shiki theme name to use for both light and dark modes.

        ```json  theme={null}
        "styling": {
          "codeblocks": {
            "theme": "dracula"
          }
        }
        ```
      </ResponseField>

      <ResponseField name="theme" type="object">
        Separate themes for light and dark modes.

        <Expandable title="theme">
          <ResponseField name="light" type="string" required>
            A Shiki theme name for light mode.
          </ResponseField>

          <ResponseField name="dark" type="string" required>
            A Shiki theme name for dark mode.
          </ResponseField>

          ```json  theme={null}
          "styling": {
            "codeblocks": {
              "theme": {
                "light": "github-light",
                "dark": "github-dark"
              }
            }
          }
          ```
        </Expandable>
      </ResponseField>

      <ResponseField name="languages" type="object">
        Custom language configuration for code blocks.

        <Expandable title="languages">
          <ResponseField name="custom" type="array of string">
            Paths to JSON files describing custom Shiki languages. Use this to add syntax highlighting for languages not included in Shiki's default set.

            The JSON file must follow the [TextMate grammar format](https://macromates.com/manual/en/language_grammars) used by Shiki.

            ```json  theme={null}
            "styling": {
              "codeblocks": {
                "languages": {
                  "custom": ["/languages/my-custom-language.json"]
                }
              }
            }
            ```
          </ResponseField>
        </Expandable>
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="icons" type="object">
  Icon library settings.

  <Expandable title="Icons">
    <ResponseField name="library" type="&#x22;fontawesome&#x22; | &#x22;lucide&#x22;" required>
      Icon library to use throughout your documentation. Defaults to `fontawesome`.

      You can only use one icon library for your project. All icon names in your documentation must come from the same library.

      <Note>
        You can specify a URL to an externally hosted icon or a path to an icon file in your project for any individual icon, regardless of the library setting.
      </Note>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fonts" type="object">
  Set custom fonts for your documentation. The default font varies by theme.

  <Expandable title="Fonts">
    <ResponseField name="family" type="string" required>
      Font family, such as "Open Sans." Supports [Google Fonts](https://fonts.google.com) family names.
    </ResponseField>

    <ResponseField name="weight" type="number">
      Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.
    </ResponseField>

    <ResponseField name="source" type="string (uri)">
      One of:

      * URL to a hosted font, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2).
      * Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

      [Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
    </ResponseField>

    <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
      Font file format. Required when using the `source` field.
    </ResponseField>

    <ResponseField name="heading" type="object">
      Override font settings specifically for headings.

      <Expandable title="Heading">
        <ResponseField name="family" type="string" required>
          Font family, such as "Open Sans", "Playfair Display." Supports [Google Fonts](https://fonts.google.com) family names.
        </ResponseField>

        <ResponseField name="weight" type="number">
          Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
        </ResponseField>

        <ResponseField name="source" type="string (uri)">
          One of:

          * URL to a hosted font, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2).
          * Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

          [Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
        </ResponseField>

        <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
          Font file format. Required when using the `source` field.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="body" type="object">
      Override font settings specifically for body text.

      <Expandable title="Body">
        <ResponseField name="family" type="string" required>
          Font family, such as "Open Sans", "Playfair Display." Supports [Google Fonts](https://fonts.google.com) family names.
        </ResponseField>

        <ResponseField name="weight" type="number">
          Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
        </ResponseField>

        <ResponseField name="source" type="string (uri)">
          One of:

          * URL to a hosted font, such as [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2).
          * Path to a local font file, such as `/fonts/Hubot-Sans.woff2`.

          [Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.
        </ResponseField>

        <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
          Font file format. Required when using the `source` field.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="object">
  Light/dark mode toggle settings.

  <Expandable title="Appearance">
    <ResponseField name="default" type="&#x22;system&#x22; | &#x22;light&#x22; | &#x22;dark&#x22;">
      Default theme mode. Choose `system` to match users' OS settings, or `light` or `dark` to force a specific mode. Defaults to `system`.
    </ResponseField>

    <ResponseField name="strict" type="boolean">
      Whether to hide the light/dark mode toggle. Defaults to `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="background" type="object">
  Background color and decoration settings.

  <Expandable title="Background">
    <ResponseField name="image" type="string or object">
      Background image for your site. Can be a single file or separate files for light and dark mode.

      <Expandable title="Image">
        <ResponseField name="light" type="string" required>
          Path to your background image for light mode. Include the file extension. Example: `/background.png`.
        </ResponseField>

        <ResponseField name="dark" type="string" required>
          Path to your background image for dark mode. Include the file extension. Example: `/background-dark.png`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="decoration" type="&#x22;gradient&#x22; | &#x22;grid&#x22; | &#x22;windows&#x22;">
      Background decoration for your theme.
    </ResponseField>

    <ResponseField name="color" type="object">
      Custom background colors for light and dark modes.

      <Expandable title="Color">
        <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
          Background color for light mode.

          Must be a hex code beginning with `#`.
        </ResponseField>

        <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
          Background color for dark mode.

          Must be a hex code beginning with `#`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Structure

<ResponseField name="navbar" type="object">
  Navigation bar items to external links.

  <Expandable title="Navbar">
    <ResponseField name="links" type="array of object">
      Links to display in the navbar

      <Expandable title="Links">
        <ResponseField name="label" type="string" required>
          Text for the link.
        </ResponseField>

        <ResponseField name="href" type="string (uri)" required>
          Link destination. Must be a valid external URL.
        </ResponseField>

        <ResponseField name="icon" type="string">
          The icon to display.

          Options:

          * [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `fontawesome` in your `docs.json`
          * [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `lucide` in your `docs.json`
          * URL to an externally hosted icon
          * Path to an icon file in your project
          * SVG code wrapped in curly braces

          For custom SVG icons:

          1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
          2. Paste your SVG code into the SVG input field.
          3. Copy the complete `<svg>...</svg>` element from the JSX output field.
          4. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
          5. Adjust `height` and `width` as needed.
        </ResponseField>

        <ResponseField name="iconType" type="string">
          The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.

          Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="primary" type="object">
      Primary button in the navbar.

      <Expandable title="Primary">
        <ResponseField name="type" type="&#x22;button&#x22; | &#x22;github&#x22;" required>
          Button style. Choose `button` for a standard button with a label or `github` for a link to a GitHub repository with icon.
        </ResponseField>

        <ResponseField name="label" type="string" required>
          Button text. Only applies when `type` is `button`.
        </ResponseField>

        <ResponseField name="href" type="string (uri)" required>
          Button destination. Must be an external URL. If `type` is `github`, must be a GitHub repository URL.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="navigation" type="object" required>
  The navigation structure of your content.

  <Expandable title="Navigation">
    <ResponseField name="global" type="object">
      Global navigation elements that appear across all pages and sections.

      <Expandable title="Global">
        <ResponseField name="languages" type="array of object">
          Language switcher configuration for localized sites.

          <Expandable title="Languages">
            <ResponseField name="language" type="&#x22;en&#x22; | &#x22;cn&#x22; | &#x22;zh&#x22; | &#x22;zh-Hans&#x22; | &#x22;zh-Hant&#x22; | &#x22;es&#x22; | &#x22;fr&#x22; | &#x22;ja&#x22; | &#x22;jp&#x22; | &#x22;pt&#x22; | &#x22;pt-BR&#x22; | &#x22;de&#x22; | &#x22;ko&#x22; | &#x22;it&#x22; | &#x22;ru&#x22; | &#x22;id&#x22; | &#x22;ar&#x22; | &#x22;tr&#x22;" required>
              Language code in ISO 639-1 format
            </ResponseField>

            <ResponseField name="default" type="boolean">
              Whether this is the default language.
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              Whether to hide this language option by default.
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              A valid path or external link to this language version of your documentation.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="versions" type="array of object">
          Version switcher configuration for multi-version sites.

          <Expandable title="Versions">
            <ResponseField name="version" type="string" required>
              Display name of the version.

              Minimum length: 1
            </ResponseField>

            <ResponseField name="default" type="boolean">
              Whether this is the default version.
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              Whether to hide this version option by default.
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              URL or path to this version of your documentation.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="tabs" type="array of object">
          Top-level navigation tabs for organizing major sections.

          <Expandable title="Tabs">
            <ResponseField name="tab" type="string" required>
              Display name of the tab.

              Minimum length: 1
            </ResponseField>

            <ResponseField name="icon" type="string">
              The icon to display.

              Options:

              * [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `fontawesome` in your `docs.json`
              * [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `lucide` in your `docs.json`
              * URL to an externally hosted icon
              * Path to an icon file in your project
              * SVG code wrapped in curly braces

              For custom SVG icons:

              1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
              2. Paste your SVG code into the SVG input field.
              3. Copy the complete `<svg>...</svg>` element from the JSX output field.
              4. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
              5. Adjust `height` and `width` as needed.
            </ResponseField>

            <ResponseField name="iconType" type="string">
              The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.

              Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              Whether to hide this tab by default.
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              URL or path for the tab destination.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="anchors" type="array of object">
          Anchored links that appear prominently in the sidebar navigation.

          <Expandable title="Anchors">
            <ResponseField name="anchor" type="string" required>
              Display name of the anchor.

              Minimum length: 1
            </ResponseField>

            <ResponseField name="icon" type="string">
              The icon to display.

              Options:

              * [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `fontawesome` in your `docs.json`
              * [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `lucide` in your `docs.json`
              * URL to an externally hosted icon
              * Path to an icon file in your project
              * SVG code wrapped in curly braces

              For custom SVG icons:

              1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
              2. Paste your SVG code into the SVG input field.
              3. Copy the complete `<svg>...</svg>` element from the JSX output field.
              4. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
              5. Adjust `height` and `width` as needed.
            </ResponseField>

            <ResponseField name="iconType" type="string">
              The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.

              Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
            </ResponseField>

            <ResponseField name="color" type="object">
              Custom colors for the anchor.

              <Expandable title="Color">
                <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
                  Anchor color for light mode.

                  Must be a hex code beginning with `#`.
                </ResponseField>

                <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
                  Anchor color for dark mode.

                  Must be a hex code beginning with `#`.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              Whether to hide this anchor by default.
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              URL or path for the anchor destination.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="dropdowns" type="array of object">
          Dropdown menus for organizing related content.

          <Expandable title="Dropdowns">
            <ResponseField name="dropdown" type="string" required>
              Display name of the dropdown.

              Minimum length: 1
            </ResponseField>

            <ResponseField name="icon" type="string">
              The icon to display.

              Options:

              * [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `fontawesome` in your `docs.json`
              * [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `lucide` in your `docs.json`
              * URL to an externally hosted icon
              * Path to an icon file in your project
              * SVG code wrapped in curly braces

              For custom SVG icons:

              1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
              2. Paste your SVG code into the SVG input field.
              3. Copy the complete `<svg>...</svg>` element from the JSX output field.
              4. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
              5. Adjust `height` and `width` as needed.
            </ResponseField>

            <ResponseField name="iconType" type="string">
              The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.

              Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              Whether to hide this dropdown by default.
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              URL or path for the dropdown destination.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="products" type="array of object">
          Products for organizing content into sections.

          <Expandable title="Products">
            <ResponseField name="product" type="string" required>
              Display name of the product.
            </ResponseField>

            <ResponseField name="description" type="string">
              Description of the product.
            </ResponseField>

            <ResponseField name="icon" type="string">
              The icon to display.

              Options:

              * [Font Awesome](https://fontawesome.com/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `fontawesome` in your `docs.json`
              * [Lucide](https://lucide.dev/icons) icon name, if you have the `icons.library` [property](/organize/settings#param-icons) set to `lucide` in your `docs.json`
              * URL to an externally hosted icon
              * Path to an icon file in your project
              * SVG code wrapped in curly braces

              For custom SVG icons:

              1. Convert your SVG using the [SVGR converter](https://react-svgr.com/playground/).
              2. Paste your SVG code into the SVG input field.
              3. Copy the complete `<svg>...</svg>` element from the JSX output field.
              4. Wrap the JSX-compatible SVG code in curly braces: `icon={<svg ...> ... </svg>}`.
              5. Adjust `height` and `width` as needed.
            </ResponseField>

            <ResponseField name="iconType" type="string">
              The [Font Awesome](https://fontawesome.com/icons) icon style. Only used with Font Awesome icons.

              Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="languages" type="array of object">
      Language switcher for [multi-language](/organize/navigation#languages) sites.
    </ResponseField>

    <ResponseField name="versions" type="array of object">
      Version switcher for sites with multiple [versions](/organize/navigation#versions).
    </ResponseField>

    <ResponseField name="tabs" type="array of object">
      Top-level navigation [tabs](/organize/navigation#tabs).
    </ResponseField>

    <ResponseField name="anchors" type="array of object">
      Sidebar [anchors](/organize/navigation#anchors).
    </ResponseField>

    <ResponseField name="dropdowns" type="array of object">
      [Dropdowns](/organize/navigation#dropdowns) for grouping related content.
    </ResponseField>

    <ResponseField name="products" type="array of object">
      Product switcher for sites with multiple [products](/organize/navigation#products).
    </ResponseField>

    <ResponseField name="groups" type="array of object">
      [Groups](/organize/navigation#groups) for organizing content into sections.
    </ResponseField>

    <ResponseField name="pages" type="array of string or object">
      Individual [pages](/organize/navigation#pages) that make up your documentation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="interaction" type="object">
  User interaction settings for navigation elements.

  <Expandable title="Interaction">
    <ResponseField name="drilldown" type="boolean">
      Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group expands. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadata configuration for documentation pages.

  <Expandable title="Metadata">
    <ResponseField name="timestamp" type="boolean">
      Enable the last modified date on all pages. When enabled, all pages display the date the content was last modified. Defaults to `false`.

      You can override this setting on individual pages with the `timestamp` frontmatter field. See [Pages](/organize/pages#last-modified-timestamp) for more information.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="footer" type="object">
  Footer content and social media links.

  <Expandable title="Footer">
    <ResponseField name="socials" type="object">
      Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example:

      ```json  theme={null}
      {
        "x": "https://x.com/mintlify"
      }
      ```

      Valid property names: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast`
    </ResponseField>

    <ResponseField name="links" type="array of object">
      Links to display in the footer.

      <Expandable title="Links">
        <ResponseField name="header" type="string">
          Header title for the column.

          Minimum length: 1
        </ResponseField>

        <ResponseField name="items" type="array of object" required>
          Links to display in the column.

          <Expandable title="Items">
            <ResponseField name="label" type="string" required>
              Link text.

              Minimum length: 1
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              Link destination URL.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="banner" type="object">
  Site-wide banner displayed at the top of pages.

  <Expandable title="Banner">
    <ResponseField name="content" type="string" required>
      The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported. For example:

      ```json  theme={null}
      {
        "content": "🚀 Banner is live! [Learn more](mintlify.com)"
      }
      ```
    </ResponseField>

    <ResponseField name="dismissible" type="boolean">
      Whether to show the dismiss button on the right side of the banner. Defaults to `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="redirects" type="array of object">
  Redirects for moved, renamed, or deleted pages.

  <Expandable title="Redirects">
    <ResponseField name="source" type="string" required>
      Source path to redirect from. Example: `/old-page`
    </ResponseField>

    <ResponseField name="destination" type="string" required>
      Destination path to redirect to. Example: `/new-page`
    </ResponseField>

    <ResponseField name="permanent" type="boolean">
      Whether to use a permanent redirect (301). Defaults to `true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="contextual" type="object">
  Contextual menu for AI-optimized content and integrations.

  <Expandable title="Contextual">
    <ResponseField name="options" type="array of &#x22;copy&#x22; | &#x22;view&#x22; | &#x22;chatgpt&#x22; | &#x22;claude&#x22; | &#x22;perplexity&#x22; | &#x22;mcp&#x22; | &#x22;cursor&#x22; | &#x22;vscode&#x22; | object" required>
      Actions available in the contextual menu. The first option appears as the default.

      * `copy`: Copy the current page as Markdown to the clipboard.
      * `view`: View the current page as Markdown in a new tab.
      * `chatgpt`: Send the current page content to ChatGPT.
      * `claude`: Send the current page content to Claude.
      * `perplexity`: Send the current page content to Perplexity.
      * `mcp`: Copies your MCP server URL to the clipboard.
      * `cursor`: Installs your hosted MCP server in Cursor.
      * `vscode`: Installs your hosted MCP server in VSCode.

      Define custom contextual menu options as objects with the following properties:

      <Expandable title="Custom option">
        <ResponseField name="title" type="string" required>
          Display title for the custom option.
        </ResponseField>

        <ResponseField name="description" type="string" required>
          Description text for the custom option.
        </ResponseField>

        <ResponseField name="icon" type="string">
          Icon for the custom option. Supports icon library names, URLs, paths, or SVG code.
        </ResponseField>

        <ResponseField name="href" type="string or object" required>
          Link destination for the custom option. Can be a simple URL string or an object with `base` and optional `query` parameters.

          Placeholder values:

          * `$page`: Current page content
          * `$path`: Current page path
          * `$mcp`: MCP server URL
        </ResponseField>
      </Expandable>

      <img src="https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=8833b554020642ceb0495df962ae833b" alt="Contextual Menu" className="rounded-xl" data-og-width="1348" width="1348" data-og-height="824" height="824" data-path="images/page-context-menu.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=280&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=7a0efdfd96e69fa3c8ebd6e9f99f4b00 280w, https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=560&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=47d1dbd6083d226fed80f4b72f4222c9 560w, https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=840&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=41ba28c312c712498667ec1ccefe19dc 840w, https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=1100&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=88343286a1eefd010a309e6d0149c1f6 1100w, https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=1650&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=9aa4f98ec00564bfd1411d94185a5942 1650w, https://mintcdn.com/mintlify/f7fo9pnTEtzBD70_/images/page-context-menu.png?w=2500&fit=max&auto=format&n=f7fo9pnTEtzBD70_&q=85&s=47ed706ae17656ec0f2ad1d58d024a0b 2500w" />

      <Note>
        The contextual menu is only available on preview and production deployments.
      </Note>
    </ResponseField>
  </Expandable>
</ResponseField>

### API configurations

<ResponseField name="api" type="object">
  API documentation and interactive playground settings.

  <Expandable title="api">
    <ResponseField name="openapi" type="string or array or object">
      OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

      <Expandable title="openapi">
        <ResponseField name="source" type="string">
          URL or path to your OpenAPI specification file.

          Minimum length: 1
        </ResponseField>

        <ResponseField name="directory" type="string">
          Directory to search for OpenAPI files.

          Do not include a leading slash.
        </ResponseField>
      </Expandable>

      <CodeGroup>
        ```json Single file theme={null}
        "openapi": "openapi.json"
        ```

        ```json Multiple files theme={null}
        "openapi": [
          "openapi/v1.json",
          "openapi/v2.json",
          "https://api.example.com/openapi.yaml"
        ]
        ```

        ```json Directory theme={null}
        "openapi": {
          "source": "openapi.json",
          "directory": "api-docs"
        }
        ```
      </CodeGroup>
    </ResponseField>

    <ResponseField name="asyncapi" type="string or array or object">
      AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

      <Expandable title="asyncapi">
        <ResponseField name="source" type="string">
          URL or path to your AsyncAPI specification file.

          Minimum length: 1
        </ResponseField>

        <ResponseField name="directory" type="string">
          Directory to search for AsyncAPI files.

          Do not include a leading slash.
        </ResponseField>
      </Expandable>

      <CodeGroup>
        ```json Single file theme={null}
        "asyncapi": "asyncapi.json"
        ```

        ```json Multiple files theme={null}
        "asyncapi": [
          "asyncapi/events.yaml",
          "asyncapi/webhooks.yaml",
          "https://api.example.com/asyncapi.json"
        ]
        ```

        ```json Directory theme={null}
        "asyncapi": {
          "source": "asyncapi.json",
          "directory": "websockets"
        }
        ```
      </CodeGroup>
    </ResponseField>

    <ResponseField name="params" type="object">
      Display settings for API parameters.

      <Expandable title="Params">
        <ResponseField name="expanded" type="&#x22;all&#x22; | &#x22;closed&#x22;">
          Whether to expand all parameters by default. Defaults to `closed`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="playground" type="object">
      API playground settings.

      <Expandable title="Playground">
        <ResponseField name="display" type="&#x22;interactive&#x22; | &#x22;simple&#x22; | &#x22;none&#x22;">
          The display mode of the API playground. Defaults to `interactive`.
        </ResponseField>

        <ResponseField name="proxy" type="boolean">
          Whether to pass API requests through a proxy server. Defaults to `true`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="examples" type="object">
      Configurations for the autogenerated API examples.

      <Expandable title="Examples">
        <ResponseField name="languages" type="array of string">
          Example languages for the autogenerated API snippets. Supported languages include:

          * `bash` (displayed as cURL)
          * `go`
          * `java`
          * `javascript`
          * `node` (displayed as Node.js)
          * `php`
          * `powershell`
          * `python`
          * `ruby`
          * `swift`

          Common aliases are also supported: `curl`, `golang`, `js`,  `nodejs`, `rb`, `sh`.
        </ResponseField>

        <ResponseField name="defaults" type="&#x22;required&#x22; | &#x22;all&#x22;">
          Whether to show optional parameters in API examples. Defaults to `all`.
        </ResponseField>

        <ResponseField name="prefill" type="boolean">
          Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
        </ResponseField>

        <ResponseField name="autogenerate" type="boolean">
          Whether to generate code samples for endpoints from API specifications. Defaults to `true`. When set to `false`, only manually-written code samples (from `x-codeSamples` in OpenAPI specifications or `<RequestExample>` components in MDX) appear in the API playground.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mdx" type="object">
      Configurations for API pages generated from MDX files.

      <Expandable title="Mdx">
        <ResponseField name="auth" type="object">
          Authentication configuration for MDX-based API requests.

          <Expandable title="Auth">
            <ResponseField name="method" type="&#x22;bearer&#x22; | &#x22;basic&#x22; | &#x22;key&#x22; | &#x22;cobo&#x22;">
              Authentication method for API requests.
            </ResponseField>

            <ResponseField name="name" type="string">
              Authentication name for API requests.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="server" type="string or array">
          Base URL prepended to relative paths in page-level `api` frontmatter fields. Not used when the frontmatter contains a full URL.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### SEO and search

<ResponseField name="seo" type="object">
  SEO indexing configurations.

  <Expandable title="Seo">
    <ResponseField name="metatags" type="object">
      Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/optimize/seo#common-meta-tags-reference) for options.
    </ResponseField>

    <ResponseField name="indexing" type="&#x22;navigable&#x22; | &#x22;all&#x22;">
      Specify which pages search engines should index. Choose `navigable` to index only pages that are in your `docs.json` navigation or choose `all` to index every page. Defaults to `navigable`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="object">
  Search display settings.

  <Expandable title="Search">
    <ResponseField name="prompt" type="string">
      Placeholder text to display in the search bar.
    </ResponseField>
  </Expandable>
</ResponseField>

### Integrations

<ResponseField name="integrations" type="object">
  Third-party integrations.

  <Expandable title="Integrations">
    <ResponseField name="amplitude" type="object">
      Amplitude analytics integration.

      <Expandable title="Amplitude">
        <ResponseField name="apiKey" type="string" required>
          Your Amplitude API key.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clarity" type="object">
      Microsoft Clarity integration.

      <Expandable title="Clarity">
        <ResponseField name="projectId" type="string" required>
          Your Microsoft Clarity project ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="clearbit" type="object">
      Clearbit data enrichment integration.

      <Expandable title="Clearbit">
        <ResponseField name="publicApiKey" type="string" required>
          Your Clearbit API key.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fathom" type="object">
      Fathom analytics integration.

      <Expandable title="Fathom">
        <ResponseField name="siteId" type="string" required>
          Your Fathom site ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="frontchat" type="object">
      Front chat integration.

      <Expandable title="Frontchat">
        <ResponseField name="snippetId" type="string" required>
          Your Front chat snippet ID.

          Minimum length: 6
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="ga4" type="object">
      Google Analytics 4 integration.

      <Expandable title="Ga4">
        <ResponseField name="measurementId" type="string matching ^G" required>
          Your Google Analytics 4 measurement ID.

          Must match pattern: ^G
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gtm" type="object">
      Google Tag Manager integration.

      <Expandable title="Gtm">
        <ResponseField name="tagId" type="string matching ^G" required>
          Your Google Tag Manager tag ID.

          Must match pattern: ^G
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="heap" type="object">
      Heap analytics integration.

      <Expandable title="Heap">
        <ResponseField name="appId" type="string" required>
          Your Heap app ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="hightouch" type="object">
      Hightouch integration.

      <Expandable title="Hightouch">
        <ResponseField name="writeKey" type="string" required>
          Your Hightouch write key.
        </ResponseField>

        <ResponseField name="apiHost" type="string">
          Your Hightouch API host.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="hotjar" type="object">
      Hotjar integration.

      <Expandable title="Hotjar">
        <ResponseField name="hjid" type="string" required>
          Your Hotjar ID.
        </ResponseField>

        <ResponseField name="hjsv" type="string" required>
          Your Hotjar script version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="intercom" type="object">
      Intercom integration.

      <Expandable title="Intercom">
        <ResponseField name="appId" type="string" required>
          Your Intercom app ID.

          Minimum length: 6
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="logrocket" type="object">
      LogRocket integration.

      <Expandable title="Logrocket">
        <ResponseField name="appId" type="string" required>
          Your LogRocket app ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mixpanel" type="object">
      Mixpanel integration.

      <Expandable title="Mixpanel">
        <ResponseField name="projectToken" type="string" required>
          Your Mixpanel project token.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="osano" type="object">
      Osano integration.

      <Expandable title="Osano">
        <ResponseField name="scriptSource" type="string" required>
          Your Osano script source.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pirsch" type="object">
      Pirsch analytics integration.

      <Expandable title="Pirsch">
        <ResponseField name="id" type="string" required>
          Your Pirsch ID.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="posthog" type="object">
      PostHog integration.

      <Expandable title="Posthog">
        <ResponseField name="apiKey" type="string matching ^phc\_" required>
          Your PostHog API key.

          Must match pattern: ^phc\_
        </ResponseField>

        <ResponseField name="apiHost" type="string (uri)">
          Your PostHog API host.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="plausible" type="object">
      Plausible analytics integration.

      <Expandable title="Plausible">
        <ResponseField name="domain" type="string" required>
          Your Plausible domain.
        </ResponseField>

        <ResponseField name="server" type="string">
          Your Plausible server.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="segment" type="object">
      Segment integration.

      <Expandable title="Segment">
        <ResponseField name="key" type="string" required>
          Your Segment key.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="telemetry" type="object">
      Telemetry settings.

      <Expandable title="Telemetry">
        <ResponseField name="enabled" type="boolean">
          Whether to enable telemetry.

          <Note>
            When set to `false`, feedback features are also disabled and do not appear on your documentation pages.
          </Note>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cookies" type="object">
      Cookie settings.

      <Expandable title="Cookies">
        <ResponseField name="key" type="string">
          Key for cookies.
        </ResponseField>

        <ResponseField name="value" type="string">
          Value for cookies.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

<ResponseField name="errors" type="object">
  Error handling settings.

  <Expandable title="Errors">
    <ResponseField name="404" type="object">
      404 "Page not found" error handling.

      <Expandable title="404">
        <ResponseField name="redirect" type="boolean">
          Whether to automatically redirect to the home page when a page is not found. Defaults to `true`.
        </ResponseField>

        <ResponseField name="title" type="string">
          Custom title for the 404 error page.
        </ResponseField>

        <ResponseField name="description" type="string">
          Custom description for the 404 error page. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<Tabs>
  <Tab title="Basic example">
    ```json docs.json  theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. is a company that provides example content and placeholder text.",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "dropdowns": [
          {
            "dropdown": "Documentation",
            "icon": "book",
            "description": "How to use the Example Co. product",
            "groups": [
              {
                "group": "Getting started",
                "pages": [
                  "index",
                  "quickstart"
                ]
              },
              {
                "group": "Customization",
                "pages": [
                  "settings",
                  "users",
                  "features"
                ]
              },
              {
                "group": "Billing",
                "pages": [
                  "billing/overview",
                  "billing/payments",
                  "billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "Changelog",
            "icon": "history",
            "description": "Updates and changes",
            "pages": [
              "changelog"
            ]
          }
        ]
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "Community",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "Get Started",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "Resources",
            "items": [
              {
                "label": "Customers",
                "href": "https://example.com/customers"
              },
              {
                "label": "Enterprise",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "Request Preview",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "Company",
            "items": [
              {
                "label": "Careers",
                "href": "https://example.com/careers"
              },
              {
                "label": "Blog",
                "href": "https://example.com/blog"
              },
              {
                "label": "Privacy Policy",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": [
          "copy",
          "view",
          "chatgpt",
          "claude"
        ]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "I can't be found",
          "description": "What ever **happened** to this _page_?"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Interactive API example">
    ```json docs.json {43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,72,73,74,75,76,77,78,79}  theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. is a company that provides example content and placeholder text.",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "dropdowns": [
          {
            "dropdown": "Documentation",
            "icon": "book",
            "description": "How to use the Example Co. product",
            "groups": [
              {
                "group": "Getting started",
                "pages": [
                  "index",
                  "quickstart"
                ]
              },
              {
                "group": "Customization",
                "pages": [
                  "settings",
                  "users",
                  "features"
                ]
              },
              {
                "group": "Billing",
                "pages": [
                  "billing/overview",
                  "billing/payments",
                  "billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "API reference",
            "icon": "terminal",
            "description": "How to use the Example Co. API",
            "groups": [
              {
                "group": "API reference",
                "pages": [
                  "api-reference/introduction"
                ]
              },
              {
                "group": "Endpoints",
                "openapi": {
                  "source": "openapi.json"
                }
              }
            ]
          },
          {
            "dropdown": "Changelog",
            "icon": "history",
            "description": "Updates and changes",
            "pages": [
              "changelog"
            ]
          }
        ]
      },
      "api": {
        "playground": {
          "display": "interactive"
        },
        "examples": {
          "languages": ["javascript", "curl", "python"]
        }
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "Community",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "Get Started",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "Resources",
            "items": [
              {
                "label": "Customers",
                "href": "https://example.com/customers"
              },
              {
                "label": "Enterprise",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "Request Preview",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "Company",
            "items": [
              {
                "label": "Careers",
                "href": "https://example.com/careers"
              },
              {
                "label": "Blog",
                "href": "https://example.com/blog"
              },
              {
                "label": "Privacy Policy",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": [
          "copy",
          "view",
          "chatgpt",
          "claude"
        ]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "I can't be found",
          "description": "What ever **happened** to this _page_?"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Multi-language example">
    ```json docs.json  theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. is a company that provides example content and placeholder text.",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "global": {
          "anchors": [
            {
              "anchor": "Documentation",
              "href": "https://mintlify.com/docs"
            },
            {
              "anchor": "Changelog",
              "href": "https://mintlify.com/docs/changelog"
            }
          ]
        },
        "languages": [ // [!code highlight:3]
          {
            "language": "en",
            "dropdowns": [
              {
                "dropdown": "Documentation",
                "icon": "book",
                "description": "How to use the Example Co. product",
                "pages": [
                  {
                    "group": "Getting started",
                    "pages": ["index", "quickstart"]
                  },
                  {
                    "group": "Customization",
                    "pages": ["settings", "users", "features"]
                  },
                  {
                    "group": "Billing",
                    "pages": [
                      "billing/overview",
                      "billing/payments",
                      "billing/subscriptions"
                    ]
                  }
                ]
              },
              {
                "dropdown": "Changelog",
                "icon": "history",
                "description": "Updates and changes",
                "pages": ["changelog"]
              }
            ]
          },
          {
            "language": "es",// [!code highlight]
            "dropdowns": [
              {
                "dropdown": "Documentación",
                "icon": "book",
                "description": "Cómo usar el producto de Example Co.",
                "pages": [
                  {
                    "group": "Comenzando",
                    "pages": ["es/index", "es/quickstart"]
                  },
                  {
                    "group": "Personalización",
                    "pages": ["es/settings", "es/users", "es/features"]
                  },
                  {
                    "group": "Billing",
                    "pages": [
                      "es/billing/overview",
                      "es/billing/payments",
                      "es/billing/subscriptions"
                    ]
                  }
                ]
              },
              {
                "dropdown": "Changelog",
                "icon": "history",
                "description": "Actualizaciones y cambios",
                "pages": ["es/changelog"]
              }
            ]
          }
        ]
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "Community",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "Get Started",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "Resources",
            "items": [
              {
                "label": "Customers",
                "href": "https://example.com/customers"
              },
              {
                "label": "Enterprise",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "Request Preview",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "Company",
            "items": [
              {
                "label": "Careers",
                "href": "https://example.com/careers"
              },
              {
                "label": "Blog",
                "href": "https://example.com/blog"
              },
              {
                "label": "Privacy Policy",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": ["copy", "view", "chatgpt", "claude"]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "I can't be found",
          "description": "What ever **happened** to this _page_?"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Upgrading from `mint.json`

If your docs project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`.

<Steps>
  <Step title="Install or update the CLI">
    If you haven't installed the [CLI](/installation), install it now:

    <CodeGroup>
      ```bash npm theme={null}
      npm i -g mint
      ```

      ```bash yarn theme={null}
      yarn global add mint
      ```

      ```bash pnpm theme={null}
      pnpm add -g mint
      ```
    </CodeGroup>

    If you already have the CLI installed, make sure it is up to date:

    ```bash  theme={null}
    mint update
    ```
  </Step>

  <Step title="Create your docs.json file">
    In your docs repository, run:

    ```bash  theme={null}
    mint upgrade
    ```

    This command creates a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
  </Step>

  <Step title="Delete your mint.json file">
    After verifying your `docs.json` is configured properly, you can safely delete your old `mint.json` file.
  </Step>
</Steps>