Settings

Configure the global settings for your documentation

Configuration Reference

Every documentation site requires a docs.json file that contains the core configuration settings.

This file controls everything from styling and navigation to integrations.

Customization

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

name · string · required

The name of the project, organization, or product Minimum length: 1

description · string

Optional description used for SEO and LLM indexing

colors · 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

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

The primary color of the theme

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The light color of the theme. Used for dark mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The dark color of the theme. Used for light mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

logo · string or object

The logo (for both light and dark mode)

Show Logo

light · string · required

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

dark · string · required

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

href · 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

favicon · 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

light · string · required

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

dark · string · required

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

styling · object

Styling configurations

Show Styling

eyebrows · "section" | "breadcrumbs"

The eyebrows style of the content. Defaults to section.

codeblocks · "system" | "dark"

The codeblock theme. Defaults to system.

icons · object

Icon library settings

Show Icons

library · "fontawesome" | "lucide" · required

The icon library to be used. Defaults to fontawesome.

fonts · object

Show Fonts

family · string · required

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

weight · number

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

source · string (uri)

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

format · "woff" | "woff2"

The font format, can be one of woff, woff2

heading · object

Show Heading

family · string · required

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

weight · number

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

source · string (uri)

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

format · "woff" | "woff2"

The font format, can be one of woff, woff2

body · object

Show Body

family · string · required

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

weight · number

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

source · string (uri)

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

format · "woff" | "woff2"

The font format, can be one of woff, woff2

appearance · object

Light / dark mode toggle settings

Show Appearance

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

The default light/dark mode. Defaults to system

strict · boolean

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

background · object

Background color and decoration settings

Show Background

image · string or object

Show Image

light · string · required

dark · string · required

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

The background decoration of the theme

color · object

The colors of the background

Show Color

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

The color in hex format to use in light mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The color in hex format to use in dark mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

Structure

navbar · object

Navbar content and settings

Show Navbar

links · array of object

The links in the navbar

Show Links

label · string · required

href · string (uri) · required

A valid path or external link

primary · object

Show Primary

type · "button" | "github" · required

label · string · required

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

href · string (uri) · required

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

navigation · object · required

The navigation structure of the content

Show Navigation

global · object

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

Show Global

languages · array of object

Show Languages

language · "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

default · boolean

Whether this language is the default language

hidden · boolean

Whether the current option is default hidden

href · string (uri) · required

A valid path or external link

versions · array of object

Show Versions

version · string · required

The name of the version

Minimum length: 1

default · boolean

Whether this version is the default version

hidden · boolean

Whether the current option is default hidden

href · string (uri) · required

An external link

tabs · array of object

Show Tabs

tab · string · required

The name of the tab

Minimum length: 1

icon · string or object

The icon to be displayed in the section

hidden · boolean

Whether the current option is default hidden

href · string (uri) · required

An external link

anchors · array of object

Show Anchors

anchor · string · required

The name of the anchor

Minimum length: 1

icon · string or object

The icon to be displayed in the section

color · object

Show Color

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

The color in hex format to use in light mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

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

The color in hex format to use in dark mode

Must match pattern: ^#([a-fA-F0-9]|[a-fA-F0-9])$

hidden · boolean

Whether the current option is default hidden

href · string (uri) · required

A valid path or external link

dropdowns · array of object

Show Dropdowns

dropdown · string · required

The name of the dropdown

Minimum length: 1

icon · string or object

The icon to be displayed in the section

hidden · boolean

Whether the current option is default hidden

href · string (uri) · required

An external link

languages · array of object

Organizing by languages

versions · array of object

Organizing by versions

tabs · array of object

Organizing by tabs

anchors · array of object

Organizing by anchors

dropdowns · array of object

Organizing by dropdowns

groups · array of object

Organizing by groups

pages · array of string or object

An array of page paths or groups

footer · object

Footer configurations

Show Footer

socials · 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

links · array of object

The links to be displayed in the footer

Show Links

header · string

The header title of the column

Minimum length: 1

items · array of object · required

The links to be displayed in the column

Show Items

label · string · required

The label of the link

Minimum length: 1

href · string (uri) · required

The url of the link

banner · object

Banner configurations

Show Banner

content · 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)"
}

dismissible · boolean

Whether the banner is dismissible. Defaults to false.

redirects · array of object

Show Redirects

source · string · required

destination · string · required

permanent · boolean

contextual · object

Show Contextual

options · 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

api · object

API reference configuration and playground settings

Show Api

openapi · 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

source · string

Minimum length: 1

directory · string

no starting slash in the directory

asyncapi · 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

source · string

Minimum length: 1

directory · string

playground · object

Configurations for the API playground

Show Playground

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

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

proxy · boolean

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

examples · object

Configurations for the autogenerated API examples

Show Examples

languages · array of string

Example languages for the autogenerated API snippets

defaults · "required" | "all"

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

mdx · object

Configurations for API pages generated from MDX files

Show Mdx

auth · object

Authentication configuration for the API

Show Auth

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

Authentication method for the API

name · string

Authentication name for the API

server · string or array

SEO & Search

seo · object

SEO indexing configurations

Show Seo

metatags · object

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

indexing · "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.

search · object

Search display settings

Show Search

prompt · string

The prompt to be displayed in the search bar placeholder

Integrations

integrations · object

Configurations for official integrations

Show Integrations

amplitude · object

Show Amplitude

apiKey · string · required

clearbit · object

Show Clearbit

publicApiKey · string · required

fathom · object

Show Fathom

siteId · string · required

frontchat · object

Show Frontchat

snippetId · string · required

Minimum length: 6

ga4 · object

Show Ga4

measurementId · string matching ^G · required

Must match pattern: ^G

gtm · object

Show Gtm

tagId · string matching ^G · required

Must match pattern: ^G

heap · object

Show Heap

appId · string · required

hotjar · object

Show Hotjar

hjid · string · required

hjsv · string · required

intercom · object

Show Intercom

appId · string · required

Minimum length: 6

koala · object

Show Koala

publicApiKey · string · required

Minimum length: 2

logrocket · object

Show Logrocket

appId · string · required

mixpanel · object

Show Mixpanel

projectToken · string · required

osano · object

Show Osano

scriptSource · string · required

pirsch · object

Show Pirsch

id · string · required

posthog · object

Show Posthog

apiKey · string matching ^phc\_ · required

Must match pattern: ^phc_

apiHost · string (uri)

plausible · object

Show Plausible

domain · string · required

server · string

segment · object

Show Segment

key · string · required

telemetry · object

Show Telemetry

enabled · boolean

cookies · object

Show Cookies

key · string

value · string

Errors

errors · object

Show Errors

404 · object

Show 404

redirect · boolean

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

Best Practices

When configuring your docs.json file, consider these best practices:

1. Keep the configuration organized by grouping related settings together
2. Use meaningful names for groups and pages in your navigation structure
3. Provide complete paths for all assets (logos, favicons, etc.)
4. Test your configuration in both light and dark modes
5. Verify all external links and integrations are correctly configured
6. Use appropriate color contrasts for accessibility
7. Configure SEO settings for better search engine visibility

Validation

The docs.json file is validated against a JSON schema to ensure proper configuration. You can reference the schema by including:

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