Global settings

Configure site-wide settings in docs.json including theme, colors, navigation, API playground, and integrations.

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
}

Reference

This section contains the full reference for the docs.json file.

Customization

theme · required

The layout theme of your site.

One of the following: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma.

See Themes for more information.

name · string · required

The name of your project, organization, or product.

colors · object · required

The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it applies to all color elements.

Show Colors

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

The primary color for your documentation. Generally used for emphasis in light mode, with some variation by theme.

Must be a hex code beginning with #.

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

The color used for emphasis in dark mode.

Must be a hex code beginning with #.

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

The color used for buttons and hover states across both light and dark modes, with some variation by theme.

Must be a hex code beginning with #.

description · string

Description of your site for SEO and AI indexing.

logo · string or object

Set your logo for both light and dark mode.

Show Logo

light · string · required

Path pointing to your logo file for light mode. Include the file extension. Example: /logo.png

dark · string · required

Path pointing to your logo file for dark mode. Include the file extension. Example: /logo-dark.png

href · string (uri)

The URL to redirect to when clicking the logo. If not provided, the logo links to the first page of the currently selected locale for internationalized docs, or to your homepage for single-language sites. Example: https://mintlify.com

favicon · string or object

Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. Can be a single file or separate files for light and dark mode. Example: /favicon.png

Show Favicon

light · string · required

Path to your favicon file for light mode. Include the file extension. Example: /favicon.png

dark · string · required

Path to your favicon file for dark mode. Include the file extension. Example: /favicon-dark.png

thumbnails · object

Thumbnail customization for social media and page previews.

Show Thumbnails

appearance · "light" | "dark"

The visual theme of your thumbnails. If not specified, thumbnails use your site’s color scheme defined by the colors field.

background · string

Background image for your thumbnails. Can be a relative path or absolute URL.

fonts · object

Font configuration for thumbnails. Only supports Google Fonts family names.

Show Fonts

family · string · required

Font family name, such as “Open Sans” or “Playfair Display.” Supports Google Fonts family names.

styling · object

Visual styling configurations.

Show Styling

eyebrows · "section" | "breadcrumbs"

The style of the page eyebrow. Choose section to show the section name or breadcrumbs to show the full navigation path. Defaults to section.

latex · boolean

Controls whether LaTeX stylesheets are included, overriding automatic detection. By default, Mintlify automatically detects LaTeX usage in your content and loads the necessary stylesheets.

• Set to true to force-load LaTeX stylesheets when automatic detection fails to recognize your mathematical expressions.
• Set to false to prevent loading LaTeX stylesheets for improved performance if you don’t use mathematical expressions but have content that triggers false-positive detection.

codeblocks · "system" | "dark" | string | object

Code block theme configuration. Defaults to "system".

Simple configuration:

• "system": Match current site mode (light or dark)
• "dark": Always use dark mode

Custom theme configuration:

• Use a string to specify a single Shiki theme for all code blocks
• Use an object to specify separate Shiki themes for light and dark modes

theme · string

A single Shiki theme name to use for both light and dark modes.

"styling": {
  "codeblocks": {
    "theme": "dracula"
  }
}

theme · object

Separate themes for light and dark modes.

Show theme

light · string · required

A Shiki theme name for light mode.

dark · string · required

A Shiki theme name for dark mode.

"styling": {
  "codeblocks": {
    "theme": {
      "light": "github-light",
      "dark": "github-dark"
    }
  }
}

languages · object

Custom language configuration for code blocks.

Show languages

custom · array of string

Paths to JSON files describing custom Shiki languages. Use this to add syntax highlighting for languages not included in Shiki’s default set.

The JSON file must follow the TextMate grammar format used by Shiki.

"styling": {
  "codeblocks": {
    "languages": {
      "custom": ["/languages/my-custom-language.json"]
    }
  }
}

icons · object

Icon library settings.

Show Icons

library · "fontawesome" | "lucide" · required

Icon library to use throughout your documentation. Defaults to fontawesome.

You can only use one icon library for your project. All icon names in your documentation must come from the same library.

You can specify a URL to an externally hosted icon or a path to an icon file in your project for any individual icon, regardless of the library setting.

fonts · object

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

Show Fonts

family · string · required

Font family, such as “Open Sans.” Supports Google Fonts family names.

weight · number

Font weight, such as 400 or 700. Variable fonts support precise weights such as 550.

source · string (uri)

One of:

• URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
• Path to a local font file, such as /fonts/Hubot-Sans.woff2.

Google Fonts are loaded automatically when you specify a Google Font family name, so no source URL is needed.

format · "woff" | "woff2"

Font file format. Required when using the source field.

heading · object

Override font settings specifically for headings.

Show Heading

family · string · required

Font family, such as “Open Sans”, “Playfair Display.” Supports Google Fonts family names.

weight · number

Font weight, such as 400, 700. Variable fonts support precise weights such as 550.

source · string (uri)

One of:

• URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
• Path to a local font file, such as /fonts/Hubot-Sans.woff2.

Google Fonts are loaded automatically when you specify a Google Font family name, so no source URL is needed.

format · "woff" | "woff2"

Font file format. Required when using the source field.

body · object

Override font settings specifically for body text.

Show Body

family · string · required

Font family, such as “Open Sans”, “Playfair Display.” Supports Google Fonts family names.

weight · number

Font weight, such as 400, 700. Variable fonts support precise weights such as 550.

source · string (uri)

One of:

• URL to a hosted font, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2.
• Path to a local font file, such as /fonts/Hubot-Sans.woff2.

Google Fonts are loaded automatically when you specify a Google Font family name, so no source URL is needed.

format · "woff" | "woff2"

Font file format. Required when using the source field.

appearance · object

Light/dark mode toggle settings.

Show Appearance

default · "system" | "light" | "dark"

Default theme mode. Choose system to match users’ OS settings, or light or dark to force a specific mode. Defaults to system.

strict · boolean

Whether to hide the light/dark mode toggle. Defaults to false.

background · object

Background color and decoration settings.

Show Background

image · string or object

Background image for your site. Can be a single file or separate files for light and dark mode.

Show Image

light · string · required

Path to your background image for light mode. Include the file extension. Example: /background.png.

dark · string · required

Path to your background image for dark mode. Include the file extension. Example: /background-dark.png.

decoration · "gradient" | "grid" | "windows"

Background decoration for your theme.

color · object

Custom background colors for light and dark modes.

Show Color

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

Background color for light mode.

Must be a hex code beginning with #.

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

Background color for dark mode.

Must be a hex code beginning with #.

variables · object

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

Show Variables

variableName · string

A key-value pair where the key is the variable name and the value is the replacement text. All variables referenced in your content must be defined, or the build fails. Variable names can contain alphanumeric characters, hyphens, and periods. Values are sanitized to prevent XSS attacks.

Structure

navbar · object

Navigation bar items to external links.

Show Navbar

links · array of object

Links to display in the navbar

Show Links

type · "github" | "discord"

Optional link type. Omit for a standard text link. Set to github to link to a GitHub repository and display the repository’s star count. Set to discord to link to a Discord server and display the number of online users in the server.

label · string

Text for the link. Required when type is not set. Optional for github and discord types. When omitted, the label is automatically populated from API data (repository name for GitHub and server name for Discord).

href · string (uri) · required

Link destination. Must be a valid external URL. For github type, must be a GitHub repository URL. For discord type, must be a Discord invite URL.

icon · string

The icon to display.

Options:

• Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
• Lucide icon name, if you have the icons.library property set to lucide in your docs.json
• Tabler icon name, if you have the icons.library property set to tabler in your docs.json
• URL to an externally hosted icon
• Path to an icon file in your project
• SVG code wrapped in curly braces

For custom SVG icons:

1. Convert your SVG using the SVGR converter.
2. Paste your SVG code into the SVG input field.
3. Copy the complete <svg>...</svg> element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
5. Adjust height and width as needed.

iconType · string

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

primary · object

Primary button in the navbar.

Show Primary

type · "button" | "github" | "discord" · required

Button style. Choose button for a standard button with a label, github for a link to a GitHub repository with live star count, or discord for a Discord server invite with live online user count.

label · string

Button text. Required when type is button. Optional for github and discord types—when omitted, the label is automatically populated from API data (repository name for GitHub, server name for Discord).

href · string (uri) · required

Button destination. Must be an external URL. If type is github, must be a GitHub repository URL. If type is discord, must be a Discord invite URL.

navigation · object · required

The navigation structure of your content.

Show Navigation

global · object

Global navigation elements that appear across all pages and sections.

Show Global

languages · array of object

Language switcher configuration for localized sites.

Show Languages

language · "ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fr" | "he" | "hi" | "id" | "it" | "ja" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "ua" | "uz" | "vi" | "zh" | "zh-Hans" | "zh-Hant" · required

Language code in ISO 639-1 format

default · boolean

Whether this is the default language.

hidden · boolean

Whether to hide this language option by default.

href · string (uri) · required

A valid path or external link to this language version of your documentation.

versions · array of object

Version switcher configuration for multi-version sites.

Show Versions

version · string · required

Display name of the version.

Minimum length: 1

default · boolean

Whether this is the default version.

hidden · boolean

Whether to hide this version option by default.

href · string (uri) · required

URL or path to this version of your documentation.

tabs · array of object

Top-level navigation tabs for organizing major sections.

Show Tabs

tab · string · required

Display name of the tab.

Minimum length: 1

icon · string

The icon to display.

Options:

• Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
• Lucide icon name, if you have the icons.library property set to lucide in your docs.json
• Tabler icon name, if you have the icons.library property set to tabler in your docs.json
• URL to an externally hosted icon
• Path to an icon file in your project
• SVG code wrapped in curly braces

For custom SVG icons:

1. Convert your SVG using the SVGR converter.
2. Paste your SVG code into the SVG input field.
3. Copy the complete <svg>...</svg> element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
5. Adjust height and width as needed.

iconType · string

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

hidden · boolean

Whether to hide this tab by default.

href · string (uri) · required

URL or path for the tab destination.

anchors · array of object

Anchored links that appear prominently in the sidebar navigation.

Show Anchors

anchor · string · required

Display name of the anchor.

Minimum length: 1

icon · string

The icon to display.

Options:

• Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
• Lucide icon name, if you have the icons.library property set to lucide in your docs.json
• Tabler icon name, if you have the icons.library property set to tabler in your docs.json
• URL to an externally hosted icon
• Path to an icon file in your project
• SVG code wrapped in curly braces

For custom SVG icons:

1. Convert your SVG using the SVGR converter.
2. Paste your SVG code into the SVG input field.
3. Copy the complete <svg>...</svg> element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
5. Adjust height and width as needed.

iconType · string

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

color · object

Custom colors for the anchor.

Show Color

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

Anchor color for light mode.

Must be a hex code beginning with #.

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

Anchor color for dark mode.

Must be a hex code beginning with #.

hidden · boolean

Whether to hide this anchor by default.

href · string (uri) · required

URL or path for the anchor destination.

dropdowns · array of object

Dropdown menus for organizing related content.

Show Dropdowns

dropdown · string · required

Display name of the dropdown.

Minimum length: 1

icon · string

The icon to display.

Options:

• Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
• Lucide icon name, if you have the icons.library property set to lucide in your docs.json
• Tabler icon name, if you have the icons.library property set to tabler in your docs.json
• URL to an externally hosted icon
• Path to an icon file in your project
• SVG code wrapped in curly braces

For custom SVG icons:

1. Convert your SVG using the SVGR converter.
2. Paste your SVG code into the SVG input field.
3. Copy the complete <svg>...</svg> element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
5. Adjust height and width as needed.

iconType · string

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

hidden · boolean

Whether to hide this dropdown by default.

href · string (uri) · required

URL or path for the dropdown destination.

products · array of object

Products for organizing content into sections.

Show Products

product · string · required

Display name of the product.

description · string

Description of the product.

icon · string

The icon to display.

Options:

• Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
• Lucide icon name, if you have the icons.library property set to lucide in your docs.json
• Tabler icon name, if you have the icons.library property set to tabler in your docs.json
• URL to an externally hosted icon
• Path to an icon file in your project
• SVG code wrapped in curly braces

For custom SVG icons:

1. Convert your SVG using the SVGR converter.
2. Paste your SVG code into the SVG input field.
3. Copy the complete <svg>...</svg> element from the JSX output field.
4. Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
5. Adjust height and width as needed.

iconType · string

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

languages · array of object

Language switcher for multi-language sites. Each language entry can include language-specific banner, footer, and navbar configurations in addition to the navigation structure.

Show Languages

language · "ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fr" | "he" | "hi" | "id" | "it" | "ja" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-Hans" | "zh-Hant" · required

Language code in ISO 639-1 format.

default · boolean

Whether this is the default language.

banner · object

Language-specific banner configuration. See banner for available options.

footer · object

Language-specific footer configuration. See footer for available options.

navbar · object

Language-specific navbar configuration. See navbar for available options.

hidden · boolean

Whether to hide this language option by default.

versions · array of object

Version switcher for sites with multiple versions.

Show Versions

default · boolean

Set to true to make this version the default. If omitted or false, the first version in the array is the default.

tag · string

Badge label displayed next to the version in the version selector. Use to highlight specific versions such as “Latest”, “Recommended”, or “Beta.”

tabs · array of object

Top-level navigation tabs.

anchors · array of object

Sidebar anchors.

dropdowns · array of object

Dropdowns for grouping related content.

products · array of object

Product switcher for sites with multiple products.

groups · array of object

Groups for organizing content into sections.

pages · array of string or object

Individual pages that make up your documentation.

interaction · object

User interaction settings for navigation elements.

Show Interaction

drilldown · boolean

Control automatic navigation behavior when selecting navigation groups. Set to true to force navigation to the first page when a navigation group expands. Set to false to prevent navigation and only expand or collapse the group. Leave unset to use the theme’s default behavior.

metadata · object

Metadata configuration for documentation pages.

Show Metadata

timestamp · boolean

Enable the last modified date on all pages. When enabled, all pages display the date the content was last modified. Defaults to false.

You can override this setting on individual pages with the timestamp frontmatter field. See Pages for more information.

footer · object

Footer content and social media links.

Show Footer

socials · object

Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL. For example:

{
  "x": "https://x.com/mintlify"
}

Valid property names: x, website, facebook, youtube, discord, slack, github, linkedin, instagram, hacker-news, medium, telegram, twitter, x-twitter, earth-americas, bluesky, threads, reddit, podcast

links · array of object

Links to display in the footer.

Show Links

header · string

Header title for the column.

Minimum length: 1

items · array of object · required

Links to display in the column.

Show Items

label · string · required

Link text.

Minimum length: 1

href · string (uri) · required

Link destination URL.

banner · object

Site-wide banner displayed at the top of pages.

Show Banner

content · string · required

The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported. For example:

{
  "content": "🚀 Banner is live! [Learn more](mintlify.com)"
}

dismissible · boolean

Whether to show the dismiss button on the right side of the banner. Defaults to false.

redirects · array of object

Redirects for moved, renamed, or deleted pages.

Show Redirects

source · string · required

Source path to redirect from. Example: /old-page

destination · string · required

Destination path to redirect to. Example: /new-page

permanent · boolean

If true, use a permanent redirect (308). If false, use a temporary redirect (307). Defaults to true.

contextual · object

Contextual menu for AI-optimized content and integrations.

Show Contextual

options · array of "assistant" | "copy" | "view" | "chatgpt" | "claude" | "perplexity" | "grok" | "mcp" | "add-mcp" | "cursor" | "vscode" | object · required

Actions available in the contextual menu. The first option appears as the default.

• assistant: Open the AI assistant with the current page as context.
• copy: Copy the current page as Markdown to the clipboard.
• view: View the current page as Markdown in a new tab.
• chatgpt: Send the current page content to ChatGPT.
• claude: Send the current page content to Claude.
• perplexity: Send the current page content to Perplexity.
• grok: Send the current page content to Grok.
• mcp: Copies your MCP server URL to the clipboard.
• add-mcp: Adds your MCP server to the user’s configuration.
• cursor: Installs your hosted MCP server in Cursor.
• vscode: Installs your hosted MCP server in VSCode.

Define custom contextual menu options as objects with the following properties:

Show Custom option

title · string · required

Display title for the custom option.

description · string · required

Description text for the custom option.

icon · string

Icon for the custom option. Supports icon library names, URLs, paths, or SVG code.

href · string or object · required

Link destination for the custom option. Can be a simple URL string or an object with base and optional query parameters.

Placeholder values:

• $page: Current page content
• $path: Current page path
• $mcp: MCP server URL

The contextual menu is only available on preview and production deployments.

display · "header" | "toc"

Where to display the contextual options. Choose header to show them in the top-of-page context menu or toc to show them in the table of contents sidebar. Defaults to header.

API configurations

api · object

API documentation and interactive playground settings.

Show api

openapi · string or array or object

OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

Show openapi

source · string

URL or path to your OpenAPI specification file.

Minimum length: 1

directory · string

Directory to search for OpenAPI files.

Do not include a leading slash.

Single file

"openapi": "openapi.json"

asyncapi · string or array or object

AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.

Show asyncapi

source · string

URL or path to your AsyncAPI specification file.

Minimum length: 1

directory · string

Directory to search for AsyncAPI files.

Do not include a leading slash.

Single file

"asyncapi": "asyncapi.json"

params · object

Display settings for API parameters.

Show Params

expanded · "all" | "closed"

Whether to expand all parameters by default. Defaults to closed.

playground · object

API playground settings.

Show Playground

display · "interactive" | "simple" | "none" | "auth"

The display mode of the API playground. Defaults to interactive. Use auth to show the playground only to authenticated users.

proxy · boolean

Whether to pass API requests through a proxy server. Defaults to true.

url · "full"

The display mode of the base URL in the endpoint header. Set to full to always show the full base URL on every endpoint page. By default, the base URL is only shown when there are multiple base URLs to select from.

examples · object

Configurations for the autogenerated API examples.

Show Examples

languages · array of string

Example languages for the autogenerated API snippets. See supported languages for the full list of available languages and aliases.

defaults · "required" | "all"

Whether to show optional parameters in API examples. Defaults to all.

prefill · boolean

Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to false.

autogenerate · boolean

Whether to generate code samples for endpoints from API specifications. Defaults to true. When set to false, only manually written code samples (from x-codeSamples in OpenAPI specifications or <RequestExample> components in MDX) appear in the API playground.

spec · object

Configurations for the OpenAPI spec.

Show Spec

download · boolean

Whether to show a download button for the OpenAPI spec on API reference pages. Defaults to false.

mdx · object

Configurations for API pages generated from MDX files.

Show Mdx

auth · object

Authentication configuration for MDX-based API requests.

Show Auth

method · "bearer" | "basic" | "key" | "cobo"

Authentication method for API requests.

name · string

Authentication name for API requests.

server · string or array

Base URL prepended to relative paths in page-level api frontmatter fields. Not used when the frontmatter contains a full URL.

SEO and search

seo · object

SEO indexing configurations.

Show Seo

metatags · object

Meta tags added to every page. Must be a valid key-value pair. See common meta tags reference for options.

indexing · "navigable" | "all"

Specify which pages search engines should index. Choose navigable to index only pages that are in your docs.json navigation or choose all to index every page. Defaults to navigable.

search · object

Search display settings.

Show Search

prompt · string

Placeholder text to display in the search bar.

Integrations

integrations · object

Third-party integrations.

Show Integrations

adobe · object

Adobe Analytics integration.

Show Adobe

launchUrl · string (uri) · required

Your Adobe Analytics launch URL.

amplitude · object

Amplitude analytics integration.

Show Amplitude

apiKey · string · required

Your Amplitude API key.

clarity · object

Microsoft Clarity integration.

Show Clarity

projectId · string · required

Your Microsoft Clarity project ID.

clearbit · object

Clearbit data enrichment integration.

Show Clearbit

publicApiKey · string · required

Your Clearbit API key.

fathom · object

Fathom analytics integration.

Show Fathom

siteId · string · required

Your Fathom site ID.

frontchat · object

Front chat integration.

Show Frontchat

snippetId · string · required

Your Front chat snippet ID.

Minimum length: 6

ga4 · object

Google Analytics 4 integration.

Show Ga4

measurementId · string matching ^G · required

Your Google Analytics 4 measurement ID.

Must match pattern: ^G

gtm · object

Google Tag Manager integration.

Show Gtm

tagId · string matching ^G · required

Your Google Tag Manager tag ID.

Must match pattern: ^G

heap · object

Heap analytics integration.

Show Heap

appId · string · required

Your Heap app ID.

hightouch · object

Hightouch integration.

Show Hightouch

writeKey · string · required

Your Hightouch write key.

apiHost · string

Your Hightouch API host.

hotjar · object

Hotjar integration.

Show Hotjar

hjid · string · required

Your Hotjar ID.

hjsv · string · required

Your Hotjar script version.

intercom · object

Intercom integration.

Show Intercom

appId · string · required

Your Intercom app ID.

Minimum length: 6

logrocket · object

LogRocket integration.

Show Logrocket

appId · string · required

Your LogRocket app ID.

mixpanel · object

Mixpanel integration.

Show Mixpanel

projectToken · string · required

Your Mixpanel project token.

pirsch · object

Pirsch analytics integration.

Show Pirsch

id · string · required

Your Pirsch ID.

posthog · object

PostHog integration.

Show Posthog

apiKey · string matching ^phc\_ · required

Your PostHog API key.

Must match pattern: ^phc_

apiHost · string (uri)

Your PostHog API host.

sessionRecording · boolean

Whether to enable session recording. Defaults to false.

plausible · object

Plausible analytics integration.

Show Plausible

domain · string · required

Your Plausible domain.

server · string

Your Plausible server.

segment · object

Segment integration.

Show Segment

key · string · required

Your Segment key.

telemetry · object

Telemetry settings.

Show Telemetry

enabled · boolean

Whether to enable telemetry.

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

cookies · object

Cookie settings.

Show Cookies

key · string

Key for cookies.

value · string

Value for cookies.

Errors

errors · object

Error handling settings.

Show Errors

404 · object

404 “Page not found” error handling.

Show 404

redirect · boolean

Whether to automatically redirect to the home page when a page is not found. Defaults to true.

title · string

Custom title for the 404 error page.

description · string

Custom description for the 404 error page. Supports MDX formatting including links, bold, italic text, and custom components.

Examples

Basic example

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. is a company that provides example content and placeholder text.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book",
        "description": "How to use the Example Co. product",
        "groups": [
          {
            "group": "Getting started",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "Customization",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "Billing",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "Changelog",
        "icon": "history",
        "description": "Updates and changes",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "type": "github",
        "href": "https://github.com/example/repo"
      },
      {
        "type": "discord",
        "href": "https://discord.gg/example"
      },
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Get Started",
      "href": "https://example.com/start"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          {
            "label": "Customers",
            "href": "https://example.com/customers"
          },
          {
            "label": "Enterprise",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "Request Preview",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "Company",
        "items": [
          {
            "label": "Careers",
            "href": "https://example.com/careers"
          },
          {
            "label": "Blog",
            "href": "https://example.com/blog"
          },
          {
            "label": "Privacy Policy",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "variables": {
    "version": "2.0.0",
    "api-url": "https://api.example.com"
  },
  "contextual": {
    "options": [
      "copy",
      "view",
      "chatgpt",
      "claude"
    ]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "I can't be found",
      "description": "What ever **happened** to this _page_?"
    }
  }
}

Interactive API example

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. is a company that provides example content and placeholder text.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book",
        "description": "How to use the Example Co. product",
        "groups": [
          {
            "group": "Getting started",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "Customization",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "Billing",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "API reference",
        "icon": "terminal",
        "description": "How to use the Example Co. API",
        "groups": [
          {
            "group": "API reference",
            "pages": [
              "api-reference/introduction"
            ]
          },
          {
            "group": "Endpoints",
            "openapi": {
              "source": "openapi.json"
            }
          }
        ]
      },
      {
        "dropdown": "Changelog",
        "icon": "history",
        "description": "Updates and changes",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "api": {
    "playground": {
      "display": "interactive"
    },
    "url": "full",
    "examples": {
      "languages": ["javascript", "curl", "python"]
    }
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "type": "github",
        "href": "https://github.com/example/repo"
      },
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "github",
      "href": "https://github.com/example/repo"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          {
            "label": "Customers",
            "href": "https://example.com/customers"
          },
          {
            "label": "Enterprise",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "Request Preview",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "Company",
        "items": [
          {
            "label": "Careers",
            "href": "https://example.com/careers"
          },
          {
            "label": "Blog",
            "href": "https://example.com/blog"
          },
          {
            "label": "Privacy Policy",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "variables": {
    "version": "2.0.0",
    "api-url": "https://api.example.com"
  },
  "contextual": {
    "options": [
      "copy",
      "view",
      "chatgpt",
      "claude"
    ]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "I can't be found",
      "description": "What ever **happened** to this _page_?"
    }
  }
}

Multi-language example

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. is a company that provides example content and placeholder text.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://mintlify.com/docs"
        },
        {
          "anchor": "Changelog",
          "href": "https://mintlify.com/docs/changelog"
        }
      ]
    },
    "languages": [ 
      {
        "language": "en",
        "dropdowns": [
          {
            "dropdown": "Documentation",
            "icon": "book",
            "description": "How to use the Example Co. product",
            "pages": [
              {
                "group": "Getting started",
                "pages": ["index", "quickstart"]
              },
              {
                "group": "Customization",
                "pages": ["settings", "users", "features"]
              },
              {
                "group": "Billing",
                "pages": [
                  "billing/overview",
                  "billing/payments",
                  "billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "Changelog",
            "icon": "history",
            "description": "Updates and changes",
            "pages": ["changelog"]
          }
        ]
      },
      {
        "language": "es",
        "dropdowns": [
          {
            "dropdown": "Documentación",
            "icon": "book",
            "description": "Cómo usar el producto de Example Co.",
            "pages": [
              {
                "group": "Comenzando",
                "pages": ["es/index", "es/quickstart"]
              },
              {
                "group": "Personalización",
                "pages": ["es/settings", "es/users", "es/features"]
              },
              {
                "group": "Billing",
                "pages": [
                  "es/billing/overview",
                  "es/billing/payments",
                  "es/billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "Changelog",
            "icon": "history",
            "description": "Actualizaciones y cambios",
            "pages": ["es/changelog"]
          }
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Get Started",
      "href": "https://example.com/start"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          {
            "label": "Customers",
            "href": "https://example.com/customers"
          },
          {
            "label": "Enterprise",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "Request Preview",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "Company",
        "items": [
          {
            "label": "Careers",
            "href": "https://example.com/careers"
          },
          {
            "label": "Blog",
            "href": "https://example.com/blog"
          },
          {
            "label": "Privacy Policy",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "variables": {
    "version": "2.0.0",
    "api-url": "https://api.example.com"
  },
  "contextual": {
    "options": ["copy", "view", "chatgpt", "claude"]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "I can't be found",
      "description": "What ever **happened** to this _page_?"
    }
  }
}

Upgrading from mint.json

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