Global settings

Configure site-wide settings in docs.json.

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
}

Customization

Theme

The layout theme of your site. Choose from: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma.

See the Themes documentation for more information.

Name

The name of your project, organization, or product.

Colors

The colors used in your documentation. Colors are applied differently across themes.

Primary color only

"colors": {
  "primary": "#3B82F6"
}

"colors": {
  "primary": "#3B82F6",
  "light": "#F8FAFC",
  "dark": "#0F172A"
}

All color values must be hex codes beginning with #.

Logo

Set your logo for both light and dark mode.

"logo": {
  "light": "/logo.png",
  "dark": "/logo-dark.png",
  "href": "https://mintlify.com"
}

Favicon

Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes.

Single favicon

"favicon": "/favicon.png"

Light and dark favicons

"favicon": {
  "light": "/favicon.png",
  "dark": "/favicon-dark.png"
}

Fonts

Set custom fonts for your documentation. The default font varies by theme.

"fonts": {
  "family": "Open Sans",
  "weight": 400,
  "heading": {
    "family": "Playfair Display",
    "weight": 700
  },
  "body": {
    "family": "Open Sans",
    "weight": 400
  }
}

Supports Google Fonts family names. Google Fonts are loaded automatically when you specify a family name.

Background

Background color and decoration settings.

"background": {
  "decoration": "gradient",
  "color": {
    "light": "#ffffff",
    "dark": "#000000"
  },
  "image": {
    "light": "/background.png",
    "dark": "/background-dark.png"
  }
}

Variables

Global variables for use throughout your documentation. Variables are replaced at build time using {{variableName}} syntax.

"variables": {
  "version": "2.0.0",
  "api-url": "https://api.example.com"
}

All variables referenced in your content must be defined, or the build will fail.

Navigation

The navigation structure of your content. See Navigation for detailed information.

"navigation": {
  "groups": [
    {
      "group": "Getting started",
      "pages": [
        "index",
        "quickstart"
      ]
    }
  ]
}

Integrations

Third-party integrations for analytics, chat, and more.

Analytics integrations

Google Analytics 4

"integrations": {
  "ga4": {
    "measurementId": "G-XXXXXXXXXX"
  }
}

"integrations": {
  "mixpanel": {
    "projectToken": "your-project-token"
  }
}

"integrations": {
  "posthog": {
    "apiKey": "phc_your-api-key",
    "apiHost": "https://app.posthog.com"
  }
}

Chat integrations

Intercom

"integrations": {
  "intercom": {
    "appId": "your-app-id"
  }
}

"integrations": {
  "frontchat": {
    "snippetId": "your-snippet-id"
  }
}

Telemetry

"integrations": {
  "telemetry": {
    "enabled": true
  }
}

When set to false, feedback features are also disabled and do not appear on your documentation pages.

SEO and search

SEO configuration

"seo": {
  "indexing": "navigable",
  "metatags": {
    "og:image": "https://example.com/image.png"
  }
}

Choose navigable to index only pages in your navigation or all to index every page. Defaults to navigable.

Search settings

"search": {
  "prompt": "Search documentation..."
}

API configurations

API documentation and interactive playground settings.

"api": {
  "openapi": "openapi.json",
  "playground": {
    "display": "interactive"
  },
  "examples": {
    "languages": ["javascript", "python", "curl"]
  }
}

See API Playground for more information.

Footer

Footer content and social media links.

"footer": {
  "socials": {
    "x": "https://x.com/mintlify",
    "github": "https://github.com/mintlify",
    "linkedin": "https://linkedin.com/company/mintlify"
  },
  "links": [
    {
      "header": "Resources",
      "items": [
        {
          "label": "Blog",
          "href": "https://mintlify.com/blog"
        }
      ]
    }
  ]
}

Navbar

Navigation bar items to external links.

"navbar": {
  "links": [
    {
      "type": "github",
      "href": "https://github.com/example/repo"
    },
    {
      "label": "Community",
      "href": "https://example.com/community"
    }
  ],
  "primary": {
    "type": "button",
    "label": "Get Started",
    "href": "https://example.com/start"
  }
}

Metadata

Metadata configuration for documentation pages.

"metadata": {
  "timestamp": true
}

Enable the last modified date on all pages. You can override this setting on individual pages with the timestamp frontmatter field.

Banner

Site-wide banner displayed at the top of pages.

"banner": {
  "content": "🚀 Banner is live! [Learn more](https://mintlify.com)",
  "dismissible": true
}

Redirects

Redirects for moved, renamed, or deleted pages.

"redirects": [
  {
    "source": "/old-page",
    "destination": "/new-page",
    "permanent": true
  }
]

Error handling

404 error page customization.

"errors": {
  "404": {
    "redirect": false,
    "title": "Page not found",
    "description": "The page you're looking for doesn't exist."
  }
}