Global Settings

Configure your documentation using the docs.json file

Every documentation site requires a docs.json file that contains the core configuration settings. This file controls 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.

Properties

Customization

theme

"mint" | "maple" | "palm"

required

The layout theme of the project. Examples: Maple, Palm,

name

string

required

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

description

string

Optional description used for SEO and LLM indexing

Styling

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"

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 false.

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

href

string (uri)

required

A valid path or external link

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" | "es" | "fr" | "jp" | "pt" | "pt-BR" | "de"

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

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

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: bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, twitter, website, x, youtube

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

redirects

array of object

Show Redirects

source

string

required

destination

string

required

permanent

boolean

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

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 false.

examples

object

Configurations for the autogenerated API examples

Show Examples

languages

array of string

Example languages for the autogenerated API snippets

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

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

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"
}

mint.json (Legacy)

Documentation for the legacy `mint.json` config file

Every Mintlify site needs a mint.json file with the core configuration settings. Learn more about the properties or from an example

Properties

Styling

name

string

required

Name of your company or project. Used for the global title.

logo

string or Logo

Path to logo image or object with path to “light” and “dark” mode logo images, and where the logo links to. SVG format is recommended. It does not pixelate and the file size is generally smaller.

Show Logo

light

string

Path to the logo in light mode. For example: /path/to/logo.svg

dark

string

Path to the logo in dark mode. For example: /path/to/logo.svg

href

string

default:

"/"

Where clicking on the logo links you to

favicon

string

Path to the favicon image. For example: /path/to/favicon.svg

colors

Colors

Hex color codes for your global theme

Show Colors

primary

string

required

The primary color. Used most often for highlighted content, section headers, accents, in light mode

light

string

The primary color for dark mode. Used most often for highlighted content, section headers, accents, in dark mode

dark

string

The primary color for important buttons

background

object

The color of the background in both light and dark mode

Show Object

light

string

required

The hex color code of the background in light mode

dark

string

required

The hex color code of the background in dark mode

theme

"venus" | "quill" | "prism"

A preset theme configuration that changes the look and feel of the project. A theme is a set of default styling configurations. Examples: Venus, Quill, Prism

layout

"topnav" | "sidenav" | "solidSidenav"

default:

"topnav"

The global layout style of the documentation.

background

Background

Set a decorative background.

Show Background

style

"gradient" | "grid" | "windows"

The style of the decorative background.

backgroundImage

string

Set a custom background image to be displayed behind every page.

font

FontDetailsType | { headings?: FontDetailsType, body?: FontDetailsType }

Custom fonts. Apply globally or set different fonts for headings and the body text.

Example:

"font": {
  "headings": {
    "family": "Roboto"
  },
  "body": {
    "family": "Oswald"
  }
}

Show FontDetailsType

family

string

required

The font family name. Custom fonts and all Google Fonts are supported. e.g. “Open Sans”, “Playfair Display”

weight

number

The font weight. Precise values such as 560 are also supported for variable fonts. Check under the Styles section for your Google Font for the available weights.

url

string

The URL to the font file. Can be used to specify a font that is not from Google Fonts.

format

'woff' | 'woff2'

The font format. Required if using a custom font source (url).

modeToggle

ModeToggle

Customize the dark mode toggle.

Show ModeToggle

default

"light" or "dark"

Set if you always want to show light or dark mode for new users. When not set, we default to the same mode as the user’s operating system.

isHidden

boolean

default:

false

Set to true to hide the dark/light mode toggle. You can combine isHidden with default to force your docs to only use light or dark mode. For example:

sidebar

Sidebar

Customize the styling of components within the sidebar.

Show Sidebar

items

"container" | "card" | "border" | "undecorated"

default:

"container"

The styling of the navigation item.

topbar

Topbar

Styling configurations for the topbar.

Show Topbar

style

"default" | "gradient"

default:

"default"

The styling of the navigation item.

search

Search

The location options for the search bar.

Show Search

location

"side" | "top"

The location of the search bar.

rounded

"default" | "sharp"

The style of the rounded edges.

codeBlock

CodeBlock

The style of the code block.

Show CodeBlock

mode

"dark" | "auto"

default:

"dark"

auto will automatically switch between light and dark mode based on the user’s system preferences.

Structure

navigation

Navigation[]

required

An array of groups with all the pages within that group

Show Navigation

group

string

The name of the group.

pages

string[]

The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array.

icon

string

The Fontawesome icon for the group. Note: this only applies to sub-folders.

iconType

string

The type of Fontawesome icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin

topbarLinks

TopbarLink[]

Array of names and urls of links you want to include in the topbar

Show TopbarLink

name

string

The name of the button.

url

string

The url once you click on the button. Example: https://mintlify.com/contact

topbarCtaButton

Call to Action

Show Topbar Call to Action

type

link or github

default:

"link"

Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.

url

string

If type is a link: What the button links to. If type is a github: Link to the repository to load GitHub information from.

name

string

Text inside the button. Only required if type is a link.

style

"pill" | "roundedRectangle"

The style of the button.

arrow

boolean

Whether to display the arrow

versions

string[]

Array of version names. Only use this if you want to show different versions of docs with a dropdown in the navigation bar.

Versions can be leveraged for localization. You can store translated content under a version, and once you specify the locale any fixed text in Mintlify, such as ‘Was this page helpful?’, will automatically be translated based on the locale. We currently support localization in English, Chinese, Spanish, French, Japanese, and Portuguese.

Localization auto-translates the UI and fixed assets in the docs, such as “Was this page helpful?”. You must translate the content of the pages yourself.

For more information, please refer to our versioning & localization documentation.

Example:

Show Version

name

string

required

The version name.

locale

string

The locale of the version. Supported locales are en, cn, es, fr, jp, pt, pt-BR, de.

default

true

Whether the version is the default version. Handy for when you have a “latest” and “stable” version and you want to default to the stable version.

anchors

Anchor[]

An array of the anchors, includes the icon, color, and url.

Show Anchor

name

string

required

The name of the anchor label.

Example: Community

icon

string

The Font Awesome icon used to feature the anchor.

Example: comments

url

string

The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.

color

string

The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties from and to that are each a hex color.

version

string

Used if you want to hide an anchor until the correct docs version is selected.

isDefaultHidden

boolean

default:

false

Pass true if you want to hide the anchor until you directly link someone to docs inside it.

iconType

string

default:

"duotone"

One of: “brands”, “duotone”, “light”, “sharp-solid”, “solid”, or “thin”

topAnchor

Anchor

Override the default configurations for the top-most anchor. Note: if you have tabs configured, this does not apply.

Show Anchor

name

string

default:

"Documentation"

required

The name of the top-most anchor

icon

string

default:

"book-open"

Font Awesome icon.

iconType

string

default:

"duotone"

One of: “brands”, “duotone”, “light”, “sharp-solid”, “solid”, or “thin”

tabs

Tabs[]

An array of navigational tabs.

Example:

"tabs": [
  {
    "name": "Writing Content",
    "url": "content"
  },
  {
    "name": "API References",
    "url": "api-playground"
  }
]

Show Tabs

name

string

The name of the tab label.

url

string

The start of the URL that marks what pages go in the tab. Generally, this is the name of the folder you put your pages in.

isDefaultHidden

boolean

default:

false

Pass true if you want to hide the tab until you directly link someone to docs inside it.

footer

{ socials?: FooterSocials, links?: FooterLinksColumn[] }

An object to configure the footer with socials and links. Example:

"footer": {
  "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" },
  "links": [
    {
      "title": "Column 1",
      "links": [
        { "label": "Column 1 Link 1", "url": "https://mintlify.com" },
        { "label": "Column 1 Link 2", "url": "https://mintlify.com" }
      ]
    },
    {
      "title": "Column 2",
      "links": [
        { "label": "Column 2 Link 1", "url": "https://mintlify.com" },
        { "label": "Column 2 Link 2", "url": "https://mintlify.com" }
      ]
    }
  ]
}

Show FooterSocials

[key]

string

One of the following values website, facebook, x, youtube, discord, slack, github, linkedin, instagram, hacker-news, medium, telegram, twitter

Example: x

value

string

The URL to the social platform.

Example: https://x.com/mintlify

Show FooterLinksColumn

title

string

Title of the column

links

{ label: string, url: string }[]

The link items in the column. External urls that starts with https:// or http:// will be opened in new tab.

feedback

Feedback

Configurations to enable feedback buttons

Show Feedback

thumbsRating

boolean

default:

false

Enables a rating system for users to indicate whether the page has been helpful

suggestEdit

boolean

default:

false

Enables a button to allow users to suggest edits via pull requests for public repositories.

If your docs repo is private, suggestEdit will not work.

raiseIssue

boolean

default:

false

Enables a button to allow users to raise an issue about the documentation

search

Search

Configurations to change the search prompt

Show Search

prompt

string

default:

"undefined"

Set the prompt for the search bar. Default is Search...

API Configurations

api

API

Configuration for API settings. Learn more about API pages at API Components.

Show API

baseUrl

string

The base url for all API endpoints. If baseUrl is an array, it will enable for multiple base url options that the user can toggle.

auth

Auth

Show Auth

method

"bearer" | "basic" | "key"

The authentication strategy used for all API endpoints.

name

string

The name of the authentication parameter used in the API playground.

If method is basic, the format should be [usernameName]:[passwordName]

inputPrefix

string

The default value that’s designed to be a prefix for the authentication input field.

E.g. If an inputPrefix of AuthKey would inherit the default input result of the authentication field as AuthKey.

playground

Playground

Configurations for the API playground

Show Playground

mode

"show" | "simple" | "hide"

default:

"show"

Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity simple

Learn more at the playground guides

disableProxy

boolean

default:

false

By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior.

Required for select request types, such as file uploads.

request

object

Configurations for API requests

Show Request

example

object

Configurations for the auto-generated API request examples

Show child attributes

languages

string[]

An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing x-codeSamples or use our default languages which include bash, python, javascript, php, go, java

paramFields

ApiParamFields

Configurations for the param fields in the API Playground

Show ApiParamFields

expanded

"all" | "topLevel" | "topLevelOneOfs" | "none"

default:

"none"

The default expanded state of expandable options in the API playground.

"all" - every expandable component is expanded

"topLevel" - every top-level expandable component is expanded

"topLevelOneOfs" - every top-level oneOf type is expanded

"none" - every expandable component is closed (default behavior)

openapi

string | string[]

A string or an array of strings of URL(s) or relative path(s) pointing to your OpenAPI file.

Examples:

Integrations

integrations

Integrations

Configurations to add third-party integrations (excluding analytics integrations)

Show Integrations

intercom

string

Enables Intercom widget on docs site. The value should be your Intercom App ID.

frontchat

string

Enables Frontchat widget on docs site. The value should be your Frontchat App ID.

analytics

Analytics

Configurations to add third-party analytics integrations. See full list of supported analytics here.

Redirects

redirects

Redirect[]

An array of paths you want to configure to permanently redirect to another path

Example:

"redirects": [
  {
    "source": "/source/path",
    "destination": "/destination/path"
  }
]

Show Redirect

source

string

The path that you want to redirect from.

Example: /source

destination

string

The path that you want to redirect to.

Example: /destination

Search Engine Optimization

seo

SEO

Settings for Search Engine Optimization.

Example:

"seo": {
  "indexHiddenPages": true
}

Show SEO

indexHiddenPages

boolean

default:

"false"

Enables indexing pages not included in navigation.

Example mint.json

Click on the following dropdown to view a sample configuration file

View Example Configuration

{
  "name": "Mintlify",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#16A34A",
    "light": "#4ADE80",
    "dark": "#166534"
  },
  "topbarLinks": [
    {
      "name": "Contact Us",
      "url": "mailto:[e-mail]"
    }
  ],
  "topbarCtaButton": {
    "name": "Get Started",
    "url": "https://mintlify.com/start"
  },
  "anchors": [
    {
      "name": "API Components",
      "icon": "rectangle-terminal",
      "color": "#f59f0b",
      "url": "api-components"
    },
    {
      "name": "Community",
      "icon": "comments",
      "color": "#2564eb",
      "url": "https://mintlify.com/community"
    }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "API Components",
      "pages": ["api-playground/overview", "api-playground/configuration"]
    },
    {
      "group": "Settings",
      "pages": ["settings/global", "settings/page"]
    },
    {
      "group": "Analytics",
      "pages": ["analytics/posthog"]
    }
  ],
  "footerSocials": {
    "github": "https://github.com/mintlify",
    "slack": "https://mintlify.com/community",
    "x": "https://x.com/mintlify"
  },
  "integrations": {
    "intercom": "APP_ID",
    "frontchat": "CHAT_ID"
  }
}