Settings

The docs.json file

Skip to the reference

Every documentation site requires a docs.json file. This file contains the global configuration settings and controls everything from styling and navigation to integrations.

Reference

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

Customization

required

One of the following: mint, maple, palm, willow, linden, almond.The layout theme of the project. Check out the Themes page for more information.

string

required

The name of the project, organization, or product

object

required

The colors to use in your documentation. At the very least, you must define the primary color. For example:

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

Show Colors

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

required

The primary color of the themeMust be a hex code beginning with #

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

The light color of the theme. Used for dark modeMust be a hex code beginning with #

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

The dark color of the theme. Used for light modeMust be a hex code beginning with #

string

Optional description used for SEO and LLM indexing

string or object

The logo (for both light and dark mode)

Show Logo

string

required

Path pointing to the light logo file to use in dark mode, including the file extension. Example: /logo.png

string

required

Path pointing to the dark logo file to use in light mode, including the file extension. Example: /logo-dark.png

string (uri)

The URL to redirect to when clicking the logo. If not provided, the logo will link to the homepage. Example: https://example.com

string or object

The path to your favicon file in the docs folder, including the file extension. The file will automatically be resized to appropriate favicon sizes. Can be a single file or a pair for light and dark mode. Example: /favicon.png

Show Favicon

string

required

Path pointing to the light favicon file to use in dark mode, including the file extension. Example: /favicon.png

string

required

Path pointing to the dark favicon file to use in light mode, including the file extension. Example: /favicon-dark.png

object

Styling configurations

Show Styling

"section" | "breadcrumbs"

The eyebrows style of the content. Defaults to section.

"system" | "dark"

The codeblock theme. Defaults to system.

object

Icon library settings

Show Icons

"fontawesome" | "lucide"

required

The icon library to be used. Defaults to fontawesome.

object

Show Fonts

string

required

The font family, such as “Open Sans”, “Playfair Display”

number

The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.

string (uri)

The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2

"woff" | "woff2"

The font format, can be one of woff, woff2

object

Show Heading

string

required

The font family, such as “Open Sans”, “Playfair Display”

number

The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.

string (uri)

The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2

"woff" | "woff2"

The font format, can be one of woff, woff2

object

Show Body

string

required

The font family, such as “Open Sans”, “Playfair Display”

number

The font weight, such as 400, 700. Precise font weights such as 550 are supported for variable fonts.

string (uri)

The font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2

"woff" | "woff2"

The font format, can be one of woff, woff2

object

Light / dark mode toggle settings

Show Appearance

"system" | "light" | "dark"

The default light/dark mode. Defaults to system

boolean

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

object

Background color and decoration settings

Show Background

string or object

Show Image

string

required

string

required

"gradient" | "grid" | "windows"

The background decoration of the theme

object

The colors of the background

Show Color

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

The color in hex format to use in light modeMust match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The color in hex format to use in dark modeMust match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

Structure

Navbar content and settings

Show Navbar

array of object

The links in the navbar

Show Links

string

required

string (uri)

required

A valid path or external link

object

Show Primary

"button" | "github"

required

string

required

The label for the primary button. This only applies when type is set to button.

string (uri)

required

A valid path or external link. If type is set to github, this will be the URL to the repository.

The navigation structure of the content

Show Navigation

object

Add external links that will appear on all sections and pages irregardless of navigation nesting

Show Global

array of object

Show Languages

"en" | "cn" | "zh" | "zh-Hans" | "zh-Hant" | "es" | "fr" | "ja" | "jp" | "pt" | "pt-BR" | "de" | "ko" | "it" | "ru" | "id" | "ar" | "tr"

required

The name of the language in the ISO 639-1 format

boolean

Whether this language is the default language

boolean

Whether the current option is default hidden

string (uri)

required

A valid path or external link

array of object

Show Versions

string

required

The name of the versionMinimum length: 1

boolean

Whether this version is the default version

boolean

Whether the current option is default hidden

string (uri)

required

An external link

array of object

Show Tabs

string

required

The name of the tabMinimum length: 1

string or object

The icon to be displayed in the section

boolean

Whether the current option is default hidden

string (uri)

required

An external link

array of object

Show Anchors

string

required

The name of the anchorMinimum length: 1

string or object

The icon to be displayed in the section

object

Show Color

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

The color in hex format to use in light modeMust match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The color in hex format to use in dark modeMust match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

boolean

Whether the current option is default hidden

string (uri)

required

A valid path or external link

array of object

Show Dropdowns

The name of the dropdownMinimum length: 1

string or object

The icon to be displayed in the section

boolean

Whether the current option is default hidden

string (uri)

required

An external link

array of object

Organizing by languages

array of object

Organizing by versions

array of object

Organizing by tabs

array of object

Organizing by anchors

array of object

Organizing by dropdowns

array of object

Organizing by groups

array of string or object

An array of page paths or groups

object

Footer configurations

Show Footer

object

An object in which each key is the name of a social media platform, and each value is the url to your profile. 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

array of object

The links to be displayed in the footer

Show Links

string

The header title of the columnMinimum length: 1

array of object

required

The links to be displayed in the column

Show Items

string

required

The label of the linkMinimum length: 1

string (uri)

required

The url of the link

object

Banner configurations

Show Banner

string

The content of the banner. This can be a string of text or a markdown string. For example:

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

boolean

Whether the banner is dismissible. Defaults to false.

array of object

Show Redirects

string

required

string

required

boolean

object

Show Contextual

array of "copy" | "view" | "chatgpt" | "claude"

required

The options to be displayed in the contextual menu. The first option is the default option.

copy: Copy the current page as markdown to the clipboard
view: View the current page as markdown in a new tab
chatgpt: Feed the current page to ChatGPT
claude: Feed the current page to Claude

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

API Configurations

object

API reference configuration and playground settings

Show Api

string or array or object

A string or an array of strings of absolute or relative urls pointing to the OpenAPI file(s)

Show Openapi

string

Minimum length: 1

string

no starting slash in the directory

string or array or object

A string or an array of strings of absolute or relative urls pointing to the AsyncAPI file(s)

Show Asyncapi

string

Minimum length: 1

string

object

Configurations for the API playground

Show Playground

"interactive" | "simple" | "none"

The display mode of the API playground. Defaults to interactive.

boolean

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

object

Configurations for the autogenerated API examples

Show Examples

array of string

Example languages for the autogenerated API snippets

"required" | "all"

Whether to show optional parameters in api examples, defaults to all

object

Configurations for API pages generated from MDX files

Show Mdx

object

Authentication configuration for the API

Show Auth

"bearer" | "basic" | "key" | "cobo"

Authentication method for the API

string

Authentication name for the API

string or array

SEO & Search

object

SEO indexing configurations

Show Seo

object

Meta tags added to every page. Must be a valid key-value pair. Possible options here

"navigable" | "all"

Specify which pages to be indexed by search engines. Setting navigable indexes pages that are set in navigation, all indexes all pages. Defaults to navigable.

object

Search display settings

Show Search

string

The prompt to be displayed in the search bar placeholder

Integrations

object

Configurations for official integrations

Show Integrations

object

Show Amplitude

string

required

object

Show Clearbit

string

required

object

Show Fathom

string

required

object

Show Frontchat

string

required

Minimum length: 6

object

Show Ga4

string matching ^G

required

Must match pattern: ^G

object

Show Gtm

string matching ^G

required

Must match pattern: ^G

object

Show Heap

string

required

object

Show Hotjar

string

required

string

required

object

Show Intercom

string

required

Minimum length: 6

object

Show Koala

string

required

Minimum length: 2

object

Show Logrocket

string

required

object

Show Mixpanel

string

required

object

Show Osano

string

required

object

Show Pirsch

string

required

object

Show Posthog

string matching ^phc\_

required

Must match pattern: ^phc_

string (uri)

object

Show Plausible

string

required

string

object

Show Segment

string

required

object

Show Telemetry

boolean

object

Show Cookies

string

Errors

object

Show Errors

object

Show 404

boolean

Whether to redirect to the home page, if the page is not found

Validation

It is advised to include the following schema reference at the top of your docs.json file to ensure proper validation while editing:

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

⌘I

Get Started

Essentials

The docs.json file

Reference

Customization

Structure

API Configurations

SEO & Search

Integrations

Errors

Validation