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

​
theme
required
The layout theme of your site.One of the following: mint, maple, palm, willow, linden, almond, aspen.See Themes for more information.
​
name
string
required
The name of your project, organization, or product.
​
colors
object
required
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.
​
description
string
Description of your site for SEO and AI indexing.
Your logo for both light and dark mode.
​
favicon
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
​
thumbnails
object
Thumbnail customization for social media and page previews.
​
styling
object
Visual styling configurations.
​
icons
object
Icon library settings.
​
fonts
object
Font configuration for your documentation. The default font is Inter.
​
appearance
object
Light/dark mode toggle settings.
​
background
object
Background color and decoration settings.

​
Structure

​
navbar
object
Navigation bar items.
​
navigation
object
required
The navigation structure of your content.
​
interaction
object
User interaction settings for navigation elements.
​
footer
object
Footer content and social media links.
​
banner
object
Site-wide banner displayed at the top of pages.
​
redirects
array of object
Redirects for moved, renamed, or deleted pages.
​
contextual
object
Contextual menu for AI-optimized content and integrations.

​
API Configurations

​
api
object
API documentation and interactive playground settings.
​
seo
object
SEO indexing configurations.
​
search
object
Search display settings.

​
Integrations

​
integrations
object
Third-party integrations.

​
Errors

​
errors
object
Error handling settings.

​
Examples

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": false,
      "title": "I can't be found",
      "description": "What ever **happened** to this _page_?"
    }
  }
}

​
Upgrading from mint.json

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

Install or update the CLI

If you haven’t installed the CLI, install it now:
npm i -g mint
If you already have the CLI installed, make sure it is up to date:
mint update
2

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

Delete your mint.json file

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