Global settings

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

required

The layout theme of your site.One of the following: mint, maple, palm, willow, linden, almond, aspen.See Themes for more information.

string

required

The name of your project, organization, or product.

object

required

The colors to use in your documentation. A primary color is required. For example:

{
  "colors": {
    "primary": "#ff0000"
  }
}

Show Colors

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

required

The primary color of your theme.Must be a hex code beginning with #.

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Light color variant of your theme.Must be a hex code beginning with #.

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Dark color variant of your theme.Must be a hex code beginning with #.

string

Description of your site for SEO and AI indexing.

string or object

Your logo for both light and dark mode.

Show Logo

string

required

Path pointing to your logo file for light mode. Include the file extension. Example: /logo.png

string

required

Path pointing to your logo file for dark mode. Include the file extension. Example: /logo-dark.png

string (uri)

The URL to redirect to when clicking the logo. If not provided, the logo will link to your homepage. Example: https://mintlify.com

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

Show Favicon

string

required

Path to your favicon file for light mode. Include the file extension. Example: /favicon.png

string

required

Path to your favicon file for dark mode. Include the file extension. Example: /favicon-dark.png

object

Thumbnail customization for social media and page previews.

Show Thumbnails

"light" | "dark"

The visual theme of your thumbnails. If not specified, thumbnails use your site’s color scheme defined by the colors field.

string

Background image for your thumbnails. Can be a relative path or absolute URL.

object

Visual styling configurations.

Show Styling

"section" | "breadcrumbs"

The style of the page eyebrow. Choose section to show the section name or breadcrumbs to show the full navigation path. Defaults to section.

"system" | "dark"

The theme of the code blocks. Choose system to match the site theme or dark for always dark code blocks. Defaults to system.

object

Icon library settings.

Show Icons

"fontawesome" | "lucide"

required

Icon library to use throughout your documentation. Defaults to fontawesome.

You can specify a URL for any individual icon, regardless of the library setting.

object

Font configuration for your documentation. The default font is Inter.

Show Fonts

string

required

Font family, such as “Open Sans”, “Playfair Display.”

number

Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.

string (uri)

URL to your font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2. Google Fonts are loaded automatically when you specify a Google Font family name, so no source URL is needed.

"woff" | "woff2"

Font file format.

object

Override font settings specifically for headings.

Show Heading

string

required

Font family, such as “Open Sans”, “Playfair Display.”

number

Font weight, such as 400, 700. Variable fonts support precise weights such as 550.

string (uri)

"woff" | "woff2"

Font file format.

object

Override font settings specifically for body text.

Show Body

string

required

Font family, such as “Open Sans”, “Playfair Display.”

number

Font weight, such as 400, 700. Variable fonts support precise weights such as 550.

string (uri)

"woff" | "woff2"

Font file format.

object

Light/dark mode toggle settings.

Show Appearance

"system" | "light" | "dark"

Default theme mode. Choose system to match users’ OS settings, or light or dark to force a specific mode. Defaults to system.

boolean

Whether to hide the light/dark mode toggle. Defaults to true.

object

Background color and decoration settings.

Show Background

string or object

Background image for your site. Can be a single file or separate files for light and dark mode.

Show Image

string

required

Path to your background image for light mode. Include the file extension. Example: /background.png.

string

required

Path to your background image for dark mode. Include the file extension. Example: /background-dark.png.

"gradient" | "grid" | "windows"

Background decoration for your theme.

object

Custom background colors for light and dark modes.

Show Color

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Background color for light mode.Must be a hex code beginning with #.

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Background color for dark mode.Must be a hex code beginning with #.

Structure

Navigation bar items.

Show Navbar

array of object

Links to display in the navbar

Show Links

string

required

Text for the link.

string (uri)

required

URL or path for the link destination.

string | object

Icon for the link. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.

object

Primary button in the navbar.

Show Primary

"button" | "github"

required

Button style. Choose button for a standard button with a label or github for a link to a GitHub repository with icon.

string

required

Button text. Only applies when type is button.

string (uri)

required

Button destination. Must be a valid path or external URL. If type is github, must be a GitHub repository URL.

The navigation structure of your content.

Show Navigation

object

Global navigation elements that appear accross all pages and sections.

Show Global

array of object

Language switcher configuration for multi-language sites.

Show Languages

"en" | "cn" | "zh" | "zh-Hans" | "zh-Hant" | "es" | "fr" | "ja" | "jp" | "pt" | "pt-BR" | "de" | "ko" | "it" | "ru" | "id" | "ar" | "tr"

required

Language code in ISO 639-1 format

boolean

Whether this is the default language.

boolean

Whether to hide this language option by default.

string (uri)

required

A valid path or external link to this language version of your documentation.

array of object

Version switcher configuration for multi-version sites.

Show Versions

string

required

Display name of the version.Minimum length: 1

boolean

Whether this is the default version.

boolean

Whether to hide this version option by default.

string (uri)

required

URL or path to this version of your documentation.

array of object

Top-level navigation tabs for organizing major sections.

Show Tabs

string

required

Display name of the tab.Minimum length: 1

string or object

Icon for the tab. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.

boolean

Whether to hide this tab by default.

string (uri)

required

URL or path for the tab destination.

array of object

Anchored links that appear prominently in the sidebar navigation.

Show Anchors

string

required

Display name of the anchor.Minimum length: 1

string or object

Icon for the anchor. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.

object

Custom colors for the anchor.

Show Color

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Anchor color for light mode.Must be a hex code beginning with #.

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

Anchor color for dark mode.Must be a hex code beginning with #.

boolean

Whether to hide this anchor by default.

string (uri)

required

URL or path for the anchor destination.

array of object

Dropdown menus for organizing related content.

Show Dropdowns

Display name of the dropdown.Minimum length: 1

string or object

Icon for the dropdown. Can be a URL (relative or external), Font Awesome icon, or Lucide icon.

boolean

Whether to hide this dropdown by default.

string (uri)

required

URL or path for the dropdown destination.

array of object

Language switcher for multi-language sites.

array of object

Version switcher for sites with multiple versions.

array of object

Top-level navigation tabs.

array of object

Sidebar anchors.

array of object

Dropdowns for grouping related content.

array of object

Groups for organizing content into sections.

array of string or object

Individual pages that make up your documentation.

object

Footer content and social media links.

Show Footer

object

Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example:

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

array of object

Links to display in the footer.

Show Links

string

Header title for the column.Minimum length: 1

array of object

required

Links to display in the column.

Show Items

string

required

Link text.Minimum length: 1

string (uri)

required

Link destination URL.

object

Site-wide banner displayed at the top of pages.

Show Banner

string

The content of the banner. Supports plain text and Markdown formatting. For example:

{
  "content": "🚀 Banner is live! [Learn more](mintlify.com)"
}

boolean

Whether users can dismiss the banner. Defaults to false.

array of object

Redirects for moved, renamed, or deleted pages.

Show Redirects

string

required

Source path to redirect from. Example: /old-page

string

required

Destination path to redirect to. Example: /new-page

boolean

Whether to use a permanent redirect (301). Defaults to true.

object

Contextual menu for AI-optimized content and integrations.

Show Contextual

array of "copy" | "view" | "chatgpt" | "claude"

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.

The contextual menu is only available on preview and production deployments.

API Configurations

object

API documentation and interactive playground settings.

Show Api

string or array or object

OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

Show Openapi

string

URL or path to your OpenAPI specification file.Minimum length: 1

string

Directory to search for OpenAPI files.Do not include a leading slash.

string or array or object

AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

Show Asyncapi

string

URL or path to your AsyncAPI specification file.Minimum length: 1

string

Directory to search for AsyncAPI files.Do not include a leading slash.

object

Display settings for API parameters.

Show Params

"all" | "closed"

Whether to expand all parameters by default. Defaults to closed.

object

API playground settings.

Show Playground

"interactive" | "simple" | "none"

The display mode of the API playground. Defaults to interactive.

boolean

Whether to pass API requests through a proxy server. Defaults to true.

object

Configurations for the autogenerated API examples.

Show Examples

array of string

Example languages for the autogenerated API snippets

"required" | "all"

Whether to show optional parameters in API examples. Defaults to all.

object

Configurations for API pages generated from MDX files.

Show Mdx

object

Authentication configuration for MDX-based API requests.

Show Auth

"bearer" | "basic" | "key" | "cobo"

Authentication method for API requests.

string

Authentication name for API requests.

string or array

Server configuration for API requests.

SEO and search

object

SEO indexing configurations.

Show Seo

object

Meta tags added to every page. Must be a valid key-value pair. See common meta tags reference for options.

"navigable" | "all"

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.

object

Search display settings.

Show Search

string

Placeholder text to display in the search bar.

Integrations

object

Third-party integrations.

Show Integrations

object

Amplitude analytics integration.

Show Amplitude

string

required

Your Amplitude API key.

object

Clearbit data enrichment integration.

Show Clearbit

string

required

Your Clearbit API key.

object

Fathom analytics integration.

Show Fathom

string

required

Your Fathom site ID.

object

Front chat integration.

Show Frontchat

string

required

Your Front chat snippet ID.Minimum length: 6

object

Google Analytics 4 integration.

Show Ga4

string matching ^G

required

Your Google Analytics 4 measurement ID.Must match pattern: ^G

object

Google Tag Manager integration.

Show Gtm

string matching ^G

required

Your Google Tag Manager tag ID.Must match pattern: ^G

object

Heap analytics integration.

Show Heap

string

required

Your Heap app ID.

object

Hotjar integration.

Show Hotjar

string

required

Your Hotjar ID.

string

required

Your Hotjar script version.

object

Intercom integration.

Show Intercom

string

required

Your Intercom app ID.Minimum length: 6

object

Koala integration.

Show Koala

string

required

Your Koala public API key.Minimum length: 2

object

LogRocket integration.

Show Logrocket

string

required

Your LogRocket app ID.

object

Mixpanel integration.

Show Mixpanel

string

required

Your Mixpanel project token.

object

Osano integration.

Show Osano

string

required

Your Osano script source.

object

Pirsch analytics integration.

Show Pirsch

string

required

Your Pirsch ID.

object

PostHog integration.

Show Posthog

string matching ^phc\_

required

Your PostHog API key.Must match pattern: ^phc_

string (uri)

Your PostHog API host.

object

Plausible analytics integration.

Show Plausible

string

required

Your Plausible domain.

string

Your Plausible server.

object

Segment integration.

Show Segment

string

required

Your Segment key.

object

Telemetry settings.

Show Telemetry

boolean

Whether to enable telemetry.

object

Cookie settings.

Show Cookies

string

Key for cookies.

string

Value for cookies.

Errors

object

Error handling settings.

Show Errors

object

404 “Page not found” error handling.

Show 404

boolean

Whether to automatically redirect to the home page when a page is not found.

Examples

Basic example
Interactive API example
Multi-language example

docs.json

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

docs.json

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

docs.json

{
  "$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": [ 
      {
        "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",
        "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.

Install or update the CLI

If you haven’t installed the CLI, 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

Create your docs.json file

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.

Delete your mint.json file

After verifying your docs.json is configured properly, you can safely delete your old mint.json file.

Getting started

Core configuration

Components

API pages

Authentication and personalization

Guides

Integrations

Version control and CI/CD

Setting up your `docs.json`

Reference

Customization

Structure

API Configurations

SEO and search

Integrations

Errors

Examples

Upgrading from `mint.json`

​Setting up your docs.json

​Reference

​Customization

​Structure

​API Configurations

​SEO and search

​Integrations

​Errors

​Examples

​Upgrading from mint.json

Setting up your `docs.json`

Reference

Customization

Structure

API Configurations

SEO and search

Integrations

Errors

Examples

Upgrading from `mint.json`