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

Field	Description
name	Your project or organization name
theme	The layout theme for your site
colors.primary	Primary brand color as a hex code
navigation	Your 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.

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

   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.