Skip to main content
The docs.json file is the central configuration file for your Mintlify documentation site. It controls the global settings for your site including visual branding, navigation structure, integrations, API settings, and more. Think of it as the blueprint for your site.

​
Required fields

You must define four fields to build a working site.
FieldDescription
nameYour project or organization name
themeThe layout theme for your site
colors.primaryPrimary brand color as a hex code
navigationYour content structure
All other fields are optional. Add them as you customize and refine your site.

​
Minimal configuration

For the best editing experience, include the $schema reference at the top of your docs.json. This enables autocomplete, validation, and inline documentation in most editors.
docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your project name",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": [
    {
      "group": "Home",
      "pages": ["index"]
    }
  ]
}

​
Settings

Appearance and branding

Customize the visual appearance of your site including theme, colors, logo, favicon, fonts, and background.

Site structure

Design the information architecture and UX of your site including the navbar, footer, banner, navigation, and redirects.

API settings

Control the display and behavior of API documentation including OpenAPI and AsyncAPI specs, API playground, and code examples.

Integrations

Connect your site to third-party services for analytics, chat, and more.

SEO & search

Control how search engines index your site including meta tags, search, and page timestamps.

Schema reference

Complete reference for all docs.json properties.

​
Split configuration with $ref

As your configuration grows, you can break docs.json into smaller files using $ref references. Each reference points to a separate JSON file that gets resolved at build time. Add a $ref property with a relative file path anywhere in your docs.json. Mintlify replaces the $ref object with the contents of the referenced file.
docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}
config/navigation.json
[
  {
    "group": "Get started",
    "pages": ["index", "quickstart"]
  },
  {
    "group": "Guides",
    "pages": ["guides/first-steps", "guides/advanced"]
  }
]
  • Referenced files can contain their own $ref references. Nested paths resolve relative to the file that contains them, not relative to docs.json.
  • References must point to valid JSON files.
  • Paths must be relative and stay within the project root. Path traversal (for example, ../../outside) is not allowed.
  • Circular references cause a build error.

​
Merging sibling keys

If a $ref resolves to an object, Mintlify merges any sibling keys in the same block on top of the referenced content, allowing those keys to take precedence over matching keys in the reference. If a $ref resolves to a non-object value such as an array, Mintlify ignores any sibling keys.
docs.json
{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}

​
Upgrading from mint.json

If your 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 creates 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 correctly, you can safely delete your old mint.json file.