Global Settings

Customize your documentation using the mint.json 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:

Only Dark Mode

"modeToggle": {
  "default": "dark",
  "isHidden": true
}

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.

For more information, please refer to our versioning documentation.

Example:

Default

"versions": ["v1.0", "v1.1"]

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.

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

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:

Absolute

"openapi": "https://example.com/openapi.json"

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 Redirect

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://1tc7vihvbit.typeform.com/to/pZJ31XZB"
  },
  "anchors": [
    {
      "name": "API Components",
      "icon": "rectangle-terminal",
      "color": "#f59f0b",
      "url": "api-components"
    },
    {
      "name": "Community",
      "icon": "comments",
      "color": "#2564eb",
      "url": "https://discord.gg/MPNgtSZkgK"
    }
  ],
  "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"
  }
}

More Customization

Learn more about how to further customize your docs with custom CSS and JS in Custom Scripts.