Global Settings

Configure your documentation using the docs.json file

Global Documentation Configuration

Every documentation site requires a docs.json file that contains the core configuration settings. This file is the central control point for everything from styling and navigation to integrations and analytics.

If you’re currently using the legacy mint.json configuration file, please update the CLI:

npm i -g mintlify@latest

And run the new upgrade command in your docs repository:

mintlify upgrade

This will generate a docs.json based off of your mint.json. Then, please delete the mint.json file from your repository.

Make sure to place your docs.json file in the root directory of your documentation project.

Core Properties

These fundamental settings define your documentation’s identity and basic configuration.

Project Information

name

string

required

The name of your project, organization, or product. This appears in various places throughout your documentation.

Minimum length: 1 character

description

string

A brief description of your documentation site. This is used for SEO purposes and LLM indexing to help users find your content.

Theme Selection

theme

"mint" | "maple" | "palm"

required

Choose the layout theme for your project. Each theme provides a unique look and feel:

• Mint: Our default modern theme
• Maple: Clean and minimalist
• Palm: Bold and engaging

Visual Customization

Configure the visual elements of your documentation to match your brand.

Brand Colors

colors

object

required

Define your documentation’s color scheme. At minimum, specify the primary color:

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

Show Color Configuration Options

primary

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

required

The primary brand color used throughout the theme

light

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

A lighter variant for dark mode contrast

dark

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

A darker variant for light mode contrast

Logo Configuration

logo

string or object

Set your documentation’s logo. You can either use a single logo or specify different versions for light and dark modes.

Show Logo Options

light

string

required

Path to the logo for light mode (e.g., /logo.svg)

dark

string

required

Path to the logo for dark mode (e.g., /logo-dark.svg)

href

string (uri)

Custom URL for logo clicks (defaults to homepage)

Favicon Settings

favicon

string or object

Configure your site’s favicon. The file will be automatically resized to appropriate favicon sizes.

Show Favicon Options

light

string

required

Light mode favicon path

dark

string

required

Dark mode favicon path

Typography & Fonts

fonts

object

Customize the typography of your documentation with custom fonts.

Show Font Configuration

family

string

required

The font family name (e.g., “Open Sans”, “Playfair Display”)

weight

number

Font weight (e.g., 400, 700). Variable fonts support precise weights.

source

string (uri)

Font file URL for custom fonts

format

'woff' | 'woff2'

Font format for custom sources

Navigation Structure

Main Navigation

navigation

object

required

Define your documentation’s navigation structure.

Show Navigation Options

global

object

Add external links that appear across all sections

groups

array of object

Organize content into logical groups

pages

array of string or object

Define individual documentation pages

Header & Footer

navbar

object

Configure the top navigation bar.

Show Navbar Options

links

array of object

Navigation links in the header

primary

object

Primary call-to-action button

footer

object

Configure the footer content and layout.

Show Footer Options

socials

object

Social media links

links

array of object

Footer navigation links

API Documentation

api

object

Settings for API reference documentation.

Show API Options

openapi

string or array

OpenAPI specification file(s)

playground

object

API playground configuration

examples

object

Code example settings

Analytics & Integrations

integrations

object

Configure third-party integrations.

Show Integration Options

amplitude

object

Amplitude analytics settings

ga4

object

Google Analytics 4 configuration

intercom

object

Intercom chat widget settings

Best Practices

When configuring your docs.json file:

1. Keep related settings grouped together
2. Use meaningful names for navigation items
3. Provide complete paths for all assets
4. Test configurations in both light and dark modes
5. Verify all external links
6. Maintain appropriate color contrast
7. Configure SEO settings properly

Use JSON schema validation to ensure your configuration is correct. Add this to your docs.json:

{
  "$schema": "https://mintlify.com/docs.json"
}

Example Configuration

View Complete Example

{
  "name": "Mintlify",
  "description": "Beautiful documentation that converts users",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#16A34A",
    "light": "#4ADE80",
    "dark": "#166534"
  },
  "navigation": {
    "pages": ["introduction", "quickstart"],
    "groups": [
      {
        "name": "Guides",
        "pages": ["guides/getting-started", "guides/advanced"]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "intercom": {
      "appId": "abc123"
    }
  }
}

Remember to validate your configuration after making changes. Use the Mintlify CLI to test your documentation locally before deploying.