Global settings

Configure your Mintlify documentation site with docs.json, the required configuration file that controls navigation, appearance, integrations, and more.

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

Store your docs.json file at the root of your documentation repository. If you have a monorepo, store your docs.json at the root of your documentation directory.

You must define four fields to build a working site.

All other fields are optional. Add them as you customize and refine your site.

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.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your project name",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    "groups": [
      {
        "group": "Home",
        "pages": ["index"]
      }
    ]
  }
}

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.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}

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

When a $ref resolves to an object, Mintlify merges sibling keys from the same block on top of the referenced content. These keys take precedence over matching keys in the reference. When a $ref resolves to a non-object value such as an array, Mintlify ignores any sibling keys.

{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}

If your project uses the deprecated mint.json file, use the CLI to upgrade to docs.json.

• Pages
• How to set up multi-language documentation
• Integrations