Skip to content

settings.mdx

Latest commit

 

History

History
1455 lines (1290 loc) · 47.1 KB

settings.mdx

File metadata and controls

1455 lines (1290 loc) · 47.1 KB
title Global settings
description Configure site-wide settings with the `docs.json` file
icon settings-2
keywords
docs.json
settings
customization
configuration

import IconsOptional from "/snippets/icons-optional.mdx";

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:

{
  "$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

The layout theme of your site.

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

See Themes for more information.

The name of your project, organization, or product. The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements. 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>
Description of your site for SEO and AI indexing. Your logo for both light and dark mode. Path pointing to your logo file for light mode. Include the file extension. Example: `/logo.png` Path pointing to your logo file for dark mode. Include the file extension. Example: `/logo-dark.png` The URL to redirect to when clicking the logo. If not provided, the logo will link to your homepage. Example: `https://mintlify.com` 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` Path to your favicon file for light mode. Include the file extension. Example: `/favicon.png` Path to your favicon file for dark mode. Include the file extension. Example: `/favicon-dark.png` Thumbnail customization for social media and page previews. The visual theme of your thumbnails. If not specified, thumbnails use your site's color scheme defined by the `colors` field. Background image for your thumbnails. Can be a relative path or absolute URL. Visual styling configurations. The style of the page eyebrow. Choose `section` to show the section name or `breadcrumbs` to show the full navigation path. Defaults to `section`. The theme of the code blocks. Choose `system` to match the site theme or `dark` for always dark code blocks. Defaults to `system`. Icon library settings. Icon library to use throughout your documentation. Defaults to `fontawesome`. 
<Note>
  You can specify a URL to an externally hosted icon, path to an icon file in your project, or JSX-compatible SVG code for any individual icon, regardless of the library setting.
</Note>
</ResponseField>
Font configuration for your documentation. The default font is [Inter](https://fonts.google.com/specimen/Inter). Font family, such as "Open Sans", "Playfair Display." Font weight, such as 400 or 700. Variable fonts support precise weights such as 550. URL to your font source, such as https://mintlify-assets.b-cdn.net/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. Font file format. Override font settings specifically for headings. 
  <Expandable title="Heading">
    <ResponseField name="family" type="string" required>
      Font family, such as "Open Sans", "Playfair Display."
    </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)">
      URL to your font source, such as https://mintlify-assets.b-cdn.net/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="&quot;woff&quot; | &quot;woff2&quot;">
      Font file format.
    </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." 
    </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)">
      URL to your font source, such as https://mintlify-assets.b-cdn.net/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="&quot;woff&quot; | &quot;woff2&quot;">
      Font file format.
    </ResponseField>
  </Expandable>
</ResponseField>
Light/dark mode toggle settings. Default theme mode. Choose `system` to match users' OS settings, or `light` or `dark` to force a specific mode. Defaults to `system`. Whether to hide the light/dark mode toggle. Defaults to `true`. Background color and decoration settings. 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="&quot;gradient&quot; | &quot;grid&quot; | &quot;windows&quot;">
  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>

Structure

Navigation bar items. 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>
      URL or path for the link destination.
    </ResponseField>
    <IconsOptional />
  </Expandable>
</ResponseField>
<ResponseField name="primary" type="object">
  Primary button in the navbar.

  <Expandable title="Primary">
    <ResponseField name="type" type="&quot;button&quot; | &quot;github&quot;" 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 a valid path or external URL. If `type` is `github`, must be a GitHub repository URL.
    </ResponseField>
  </Expandable>
</ResponseField>
The navigation structure of your content. Global navigation elements that appear accross 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="&quot;en&quot; | &quot;cn&quot; | &quot;zh&quot; | &quot;zh-Hans&quot; | &quot;zh-Hant&quot; | &quot;es&quot; | &quot;fr&quot; | &quot;ja&quot; | &quot;jp&quot; | &quot;pt&quot; | &quot;pt-BR&quot; | &quot;de&quot; | &quot;ko&quot; | &quot;it&quot; | &quot;ru&quot; | &quot;id&quot; | &quot;ar&quot; | &quot;tr&quot;" 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>
        <IconsOptional />
        <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>
        <IconsOptional />
        <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>
        <IconsOptional />
        <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>
  </Expandable>
</ResponseField>
<ResponseField name="languages" type="array of object">
  Language switcher for [multi-language](navigation#languages) sites.

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

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

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

</ResponseField>

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

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

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

</ResponseField>
User interaction settings for navigation elements. Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior. Footer content and social media links. Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example: ```json { "x": "https://x.com/mintlify" } ``` 
  Valid property names: `x`, `website`, `facebook`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter`, `x-twitter`, `earth-americas`, `bluesky`, `threads`, `reddit`, `podcast`
</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>
Site-wide banner displayed at the top of pages. The content of the banner. Supports plain text and Markdown formatting. For example: ```json { "content": "🚀 Banner is live! [Learn more](mintlify.com)" } ``` Whether users can dismiss the banner. Defaults to `false`. Redirects for moved, renamed, or deleted pages. Source path to redirect from. Example: `/old-page` Destination path to redirect to. Example: `/new-page` Whether to use a permanent redirect (301). Defaults to `true`. Contextual menu for AI-optimized content and integrations. 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. 
  <img src="/images/page-context-menu.png" alt="Contextual Menu" className="rounded-xl" />

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

API Configurations

API documentation and interactive playground settings. 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>
</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>
</ResponseField>
<ResponseField name="params" type="object">
  Display settings for API parameters.

  <Expandable title="Params">
    <ResponseField name="expanded" type="&quot;all&quot; | &quot;closed&quot;">
      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="&quot;interactive&quot; | &quot;simple&quot; | &quot;none&quot;">
      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
    </ResponseField>
     <ResponseField name="defaults" type="&quot;required&quot; | &quot;all&quot;">
      Whether to show optional parameters in API examples. Defaults to `all`.
    </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="&quot;bearer&quot; | &quot;basic&quot; | &quot;key&quot; | &quot;cobo&quot;">
          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">
      Server configuration for API requests.
    </ResponseField>
  </Expandable>
</ResponseField>

SEO and search

SEO indexing configurations. Meta tags added to every page. Must be a valid key-value pair. See [common meta tags reference](/settings/seo#common-meta-tags-reference) for options. 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`. Search display settings. Placeholder text to display in the search bar.

Integrations

Third-party integrations. Amplitude analytics integration. 
  <Expandable title="Amplitude">
    <ResponseField name="apiKey" type="string" required>
      Your Amplitude API key.
    </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="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="koala" type="object">
  Koala integration.

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

      Minimum length: 2
    </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.
    </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>

Errors

Error handling settings. 404 "Page not found" error handling. Whether to automatically redirect to the home page when a page is not found.

Examples

```json title="docs.json" wrap lines { "$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" }, "koala": { "publicApiKey": "pk_example_key_123" }, "telemetry": { "enabled": true }, "cookies": { "key": "example_cookie_key", "value": "example_cookie_value" } }, "contextual": { "options": [ "copy", "view", "chatgpt", "claude" ] }, "errors": { "404": { "redirect": true } } } ``` ```json title="docs.json" wrap lines highlight={43-61, 72-79} { "$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" }, "koala": { "publicApiKey": "pk_example_key_123" }, "telemetry": { "enabled": true }, "cookies": { "key": "example_cookie_key", "value": "example_cookie_value" } }, "contextual": { "options": [ "copy", "view", "chatgpt", "claude" ] }, "errors": { "404": { "redirect": true } } } ``` ```json title="docs.json" wrap lines { "$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" }, "koala": { "publicApiKey": "pk_example_key_123" }, "telemetry": { "enabled": true }, "cookies": { "key": "example_cookie_key", "value": "example_cookie_value" } }, "contextual": { "options": ["copy", "view", "chatgpt", "claude"] }, "errors": { "404": { "redirect": true } } } ```

Upgrading from mint.json

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

If you haven't installed the [CLI](/installation), install it now: 
npm i -g mint
yarn global add mint
pnpm add -g mint

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

mint update
In your docs repository, run: 
mint upgrade

This command will create a docs.json file from your existing mint.json. Review the generated file to ensure all settings are correct. After verifying your docs.json is configured properly, you can safely delete your old mint.json file.