settings-reference.mdx

title	docs.json schema reference
description	Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site.
keywords	docs.json schema reference configuration all settings properties complete

Required fields have a required badge. All other fields are optional.

For context on what each group of settings does, see the topic pages:

• Appearance and branding
• Site structure
• API settings
• Integrations
• SEO and search

Quick reference

Property	Type	Required	Default
$ref	string (file path)	No	None
theme	string	Yes	None
name	string	Yes	None
colors.primary	string (hex)	Yes	None
navigation	object	Yes	None
description	string	No	None
logo	string or object	No	None
favicon	string or object	No	None
appearance.default	"system" | "light" | "dark"	No	"system"
appearance.strict	boolean	No	false
fonts.family	string	No	Theme default
icons.library	"fontawesome" | "lucide" | "tabler"	No	"fontawesome"
background.decoration	"gradient" | "grid" | "windows"	No	None
styling.eyebrows	"section" | "breadcrumbs"	No	"section"
styling.latex	boolean	No	Auto-detected
styling.codeblocks	"system" | "dark" | string | object	No	"system"
thumbnails.appearance	"light" | "dark"	No	Site default
navbar.links	array	No	None
navbar.primary	object	No	None
footer.socials	object	No	None
footer.links	array	No	None
banner.content	string	No	None
banner.dismissible	boolean	No	false
banner.type	"info" | "warning" | "critical"	No	"info"
banner.color	object | string	No	None
interaction.drilldown	boolean	No	Theme default
contextual.options	array	No	None
contextual.display	"header" | "toc"	No	"header"
redirects	array	No	None
variables	object	No	None
metadata.timestamp	boolean	No	false
errors.404.redirect	boolean	No	true
errors.404.title	string	No	None
errors.404.description	string	No	None
api.openapi	string or array or object	No	None
api.asyncapi	string or array or object	No	None
api.playground.display	"interactive" | "simple" | "none" | "auth"	No	"interactive"
api.playground.proxy	boolean	No	true
api.playground.credentials	boolean	No	false
api.params.expanded	"all" | "closed"	No	"closed"
api.params.post	array of string	No	None
api.url	"full"	No	None
api.examples.languages	array of string	No	None
api.examples.defaults	"required" | "all"	No	"all"
api.examples.prefill	boolean	No	false
api.examples.autogenerate	boolean	No	true
seo.indexing	"navigable" | "all"	No	"navigable"
seo.metatags	object	No	None
search.prompt	string	No	None
integrations.*	object	No	None

Full property reference

$ref

Load configuration from another JSON file. Use $ref at any level of your docs.json to split configuration across multiple files.

Type: string—relative file path to a .json file

• When $ref resolves to an object, Mintlify merges any sibling keys in the same block on top of the referenced content, allowing those keys to take precedence over matching keys in the reference.
• When $ref resolves to a non-object value such as an array, Mintlify ignores any sibling keys.
• Referenced files can contain their own $ref entries, resolved relative to that file.
• Paths must stay within the project root. Circular references cause a build error.

See Split configuration with $ref for examples.

---

theme - required

The layout theme for your site.

Type: string Options: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma

See Themes for previews.

---

name - required

The name of your project, organization, or product.

Type: string

---

colors - required

The colors used in your documentation.

Type: object

colors.primary

required

The primary color. Generally used for emphasis in light mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

colors.light

The color used for emphasis in dark mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

colors.dark

The color used for buttons and hover states across both modes.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

---

navigation - required

The navigation structure of your content.

Type: object

See Navigation for complete documentation.

navigation.global

Global navigation elements that appear across all pages and locales.

Type: object

navigation.global.tabs

Top-level navigation tabs.

Type: array of object—each with: tab (string, required), icon (string), iconType (string), hidden (boolean), href (string uri, required)

navigation.global.anchors

Sidebar anchor links.

Type: array of object—each with: anchor (string, required), icon (string), iconType (string), color.light (string hex), color.dark (string hex), hidden (boolean), href (string uri, required)

navigation.global.dropdowns

Dropdown menus.

Type: array of object—each with: dropdown (string, required), icon (string), iconType (string), hidden (boolean), href (string uri, required)

navigation.global.languages

Language switcher in the global nav.

Type: array of object—each with: language (string, required), default (boolean), hidden (boolean), href (string uri, required)

Supported language codes: ar, ca, cn, cs, da, de, en, es, fr, fr-CA, he, hi, hu, id, it, ja, ja-JP, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, uz, vi, zh, zh-CN, zh-Hans, zh-Hant, zh-TW

navigation.global.versions

Version switcher in the global nav.

Type: array of object—each with: version (string, required, min length 1), default (boolean), hidden (boolean), href (string uri, required)

navigation.global.products

Product switcher in the global nav.

Type: array of object—each with: product (string, required), description (string), icon (string), iconType (string)

navigation.languages

Language switcher for multi-language sites. Each entry can include language-specific banner, footer, and navbar overrides.

Type: array of object—each with: language (string, required), default (boolean), hidden (boolean), banner (object), footer (object), navbar (object)

Supported language codes: ar, ca, cn, cs, da, de, en, es, fr, fr-CA, he, hi, hu, id, it, ja, ja-JP, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, uz, vi, zh, zh-CN, zh-Hans, zh-Hant, zh-TW

navigation.versions

Version switcher for multi-version sites.

Type: array of object—each with: default (boolean), tag (string)

navigation.tabs

Top-level navigation tabs.

Type: array of object—see navigation.global.tabs for shape.

navigation.anchors

Sidebar anchor links.

Type: array of object—see navigation.global.anchors for shape.

navigation.dropdowns

Dropdown menus.

Type: array of object—see navigation.global.dropdowns for shape.

navigation.products

Product switcher.

Type: array of object—see navigation.global.products for shape.

navigation.groups

Groups for organizing content into labeled sections.

Type: array of object

navigation.groups[].boost

Numeric multiplier applied to the in-product search ranking of every page in this group. Pages inherit the boost factor from the nearest ancestor group that sets one. Use values greater than 1 to prioritize, between 0 and 1 to de-prioritize. See Search.

Type: number

navigation.pages

Individual pages in your documentation.

Type: array of string or object

navigation.directory

Directory layout for root pages in navigation groups. Inherits recursively. Descendants can override. See Directory listings.

Type: "none" | "accordion" | "card"—default "none"

---

description

Site description for SEO and AI indexing.

Type: string

---

logo

Site logo. Provide a path string or separate light and dark objects.

Type: string or object

logo.light

required (when using object form)

Path to the logo for light mode. Example: /logo/light.svg.

Type: string

logo.dark

required (when using object form)

Path to the logo for dark mode. Example: /logo/dark.svg.

Type: string

logo.href

URL to redirect to when clicking the logo.

Type: string (uri)

---

favicon

Site favicon. Automatically resized. Provide a path string or separate light and dark objects.

Type: string or object

favicon.light

required (when using object form)

Path to the favicon for light mode. Example: /favicon.png.

Type: string

favicon.dark

required (when using object form)

Path to the favicon for dark mode. Example: /favicon-dark.png.

Type: string

---

appearance

Light/dark mode settings.

Type: object

appearance.default

Default color mode.

Type: "system" | "light" | "dark" Default: "system"

appearance.strict

When true, hides the light/dark mode toggle.

Type: boolean Default: false

---

fonts

Custom fonts. Supports Google Fonts and self-hosted fonts.

Type: object

fonts.family

required (when using fonts)

Font family name. Google Fonts family names load automatically.

Type: string

fonts.weight

Font weight. Variable fonts support fractional values such as 550.

Type: number

fonts.source

URL to a hosted font or path to a local font file. Not needed for Google Fonts.

Type: string (uri)

fonts.format

Font file format. Required when using fonts.source.

Type: "woff" | "woff2"

fonts.heading

Override font settings for headings. Accepts the same family, weight, source, and format fields.

Type: object

fonts.body

Override font settings for body text. Accepts the same family, weight, source, and format fields.

Type: object

---

icons

Icon library settings.

Type: object

icons.library

required

Icon library to use throughout your documentation. All icon names in your docs must come from the selected library.

Type: "fontawesome" | "lucide" | "tabler" Default: "fontawesome"

---

background

Background image, decoration, and color settings.

Type: object

background.decoration

Decorative background pattern.

Type: "gradient" | "grid" | "windows"

background.color

Custom background colors.

Type: object

background.color.light

Background color for light mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

background.color.dark

Background color for dark mode.

Type: string—hex code matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

background.image

Background image. Provide a path string or separate light and dark objects.

Type: string or object

background.image.light

required (when using object form)

Background image path for light mode.

Type: string

background.image.dark

required (when using object form)

Background image path for dark mode.

Type: string

---

styling

Visual styling controls.

Type: object

styling.eyebrows

Page eyebrow style shown at the top of the page.

Type: "section" | "breadcrumbs" Default: "section"

styling.latex

Whether to load LaTeX stylesheets. By default, Mintlify auto-detects LaTeX usage.

Type: boolean

styling.codeblocks

Code block theme configuration.

Type: "system" | "dark" | string (Shiki theme name) | object Default: "system"

When an object:

styling.codeblocks.theme

A single Shiki theme name for both modes, or an object with light and dark Shiki theme names.

Type: string or object

styling.codeblocks.languages

Custom language configuration.

Type: object

styling.codeblocks.languages.custom

Paths to JSON files describing custom Shiki languages in TextMate grammar format.

Type: array of string

---

thumbnails

Social media thumbnail customization.

Type: object

thumbnails.appearance

Visual theme for thumbnails.

Type: "light" | "dark" Default: Site color scheme

thumbnails.background

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

Type: string

thumbnails.fonts

Font configuration for thumbnails.

Type: object

thumbnails.fonts.family

required (when using thumbnails.fonts)

Font family name. Supports Google Fonts only.

Type: string

---

navbar

Top navigation bar configuration.

Type: object

navbar.links

Links displayed in the navbar.

Type: array of object—each with:

Field	Type	Required	Description
type	"github" | "discord"	No	Link type. Omit for a standard link.
label	string	Conditional	Required when type is omitted.
href	string (uri)	Yes	Link destination.
icon	string	No	Icon name, URL, path, or SVG.
iconType	string	No	Font Awesome icon style only.

navbar.primary

Primary call-to-action button in the navbar.

Type: object

Field	Type	Required	Description
type	"button" | "github" | "discord"	Yes	Button style.
label	string	Conditional	Required when type is "button".
href	string (uri)	Yes	Button destination.

---

footer

Footer content and social links.

Type: object

footer.socials

Social media profiles. Each key is a platform name, each value is your profile URL.

Type: object

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

footer.links

Link columns in the footer. Maximum 4 columns.

Type: array of object (max 4)—each with: header (string), items (array of { label: string, href: string }, required)

---

banner

Site-wide banner displayed at the top of every page.

Type: object

banner.content

required (when using banner)

Banner text. Supports basic MDX formatting including links, bold, and italic. Custom components are not supported.

Type: string

banner.dismissible

Whether to show a dismiss button.

Type: boolean Default: false

banner.type

Visual style for the banner background. Use info for general announcements, warning for cautionary notices, and critical for urgent issues.

Type: "info" | "warning" | "critical" Default: "info"

banner.color

Custom background color override. Takes precedence over type. Banner text is white, so choose a background that remains legible.

Type: object with light (string) and dark (string) hex values, or a single hex string applied to both modes.

---

interaction

Navigation interaction settings.

Type: object

interaction.drilldown

Controls automatic navigation when a user clicks a navigation group. Set to true to navigate to the first page when a user clicks a group, false to only expand/collapse the group without navigating.

Type: boolean Default: Theme default

---

contextual

Contextual menu for page actions and AI tool integrations.

Type: object

contextual.options

required

Actions available in the contextual menu. The first item is the default action.

Type: array of "assistant" | "copy" | "view" | "download-pdf" | "download-spec" | "chatgpt" | "claude" | "perplexity" | "grok" | "aistudio" | "devin" | "devin-desktop" | "mcp" | "add-mcp" | "cursor" | "vscode" | "devin-mcp" | object

Custom option object fields:

Field	Type	Required	Description
title	string	Yes	Display title.
description	string	Yes	Description text.
icon	string	No	Icon name, URL, path, or SVG.
href	string or object	Yes	Link destination. Supports $page, $path, $mcp placeholders.

contextual.display

Where to show the contextual menu.

Type: "header" | "toc" Default: "header"

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

---

redirects

Redirects for moved, renamed, or deleted pages.

Type: array of object—each with:

Field	Type	Required	Description
source	string	Yes	Path to redirect from. Example: /old-page
destination	string	Yes	Path to redirect to. Example: /new-page
permanent	boolean	No	true for 308, false for 307. Default: true.

---

variables

Global content variables replaced at build time using {{variableName}} syntax.

Type: object—key-value pairs where keys are variable names (alphanumeric and hyphens only) and values are replacement strings.

Variable substitution applies to MDX pages and snippets only. It does not apply to OpenAPI specification files (`.yaml`, `.yml`, `.json`) or other static assets.

---

metadata

Global page metadata settings.

Type: object

metadata.timestamp

Display a last-modified date on all pages. For deployments backed by GitHub or GitLab, the date reflects the last Git commit that touched a page's source file, and falls back to the most recent deployment timestamp if a Git commit date isn't available.

Type: boolean Default: false

---

errors

Error page settings.

Type: object

errors.404

Settings for the 404 "Page not found" error page.

Type: object

errors.404.redirect

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

Type: boolean Default: true

errors.404.title

Custom title for the 404 page.

Type: string

errors.404.description

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

Type: string

---

api

API documentation and playground settings.

Type: object

api.openapi

OpenAPI specification files.

Type: string | array of string | object with source (string) and directory (string)

api.asyncapi

AsyncAPI specification files.

Type: string | array of string | object with source (string) and directory (string)

api.playground

Interactive playground settings.

Type: object

api.playground.display

Playground display mode.

Type: "interactive" | "simple" | "none" | "auth" Default: "interactive"

api.playground.proxy

Whether to route API requests through a proxy.

Type: boolean Default: true

api.playground.credentials

Whether to include cookies and authentication headers for cross-origin requests when proxy is false. Has no effect when proxy is true.

Type: boolean Default: false

api.params

API parameter display settings.

Type: object

api.params.expanded

Whether to expand all parameters by default.

Type: "all" | "closed" Default: "closed"

api.params.post

OpenAPI spec field keys to surface as post pills next to every parameter name. For each key, Mintlify reads the value on the schema and renders it as a pill: strings render verbatim, true renders the key name, numbers stringify, and arrays render one pill per element. Mintlify skips false, null, empty strings, and objects.

Type: array of string

api.url

Base URL display mode.

Type: "full" Default: Only shown when multiple base URLs exist.

api.examples

Code example settings.

Type: object

api.examples.languages

Languages for autogenerated code snippets. See supported languages.

Type: array of string

api.examples.defaults

Whether to include optional parameters in examples.

Type: "required" | "all" Default: "all"

api.examples.prefill

Whether to prefill playground fields with spec example values.

Type: boolean Default: false

api.examples.autogenerate

Whether to generate code samples from API specifications.

Type: boolean Default: true

api.mdx

Settings for API pages built from MDX files.

Type: object

api.mdx.auth

Authentication configuration for MDX-based API requests.

Type: object

api.mdx.auth.method

Authentication method.

Type: "bearer" | "basic" | "key" | "cobo"

api.mdx.auth.name

Authentication parameter name.

Type: string

api.mdx.server

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

Type: string or array

---

seo

Search engine optimization settings.

Type: object

seo.indexing

Which pages search engines should index.

Type: "navigable" | "all" Default: "navigable"

seo.metatags

Custom meta tags added to every page. Key-value pairs.

Type: object

---

search

Search bar settings.

Type: object

search.prompt

Placeholder text in the search bar.

Type: string

---

integrations

Third-party integrations.

Type: object

Property	Type	Required field	Description
integrations.adobe.launchUrl	string (uri)	Yes	Adobe Analytics launch URL.
integrations.amplitude.apiKey	string	Yes	Amplitude API key.
integrations.clarity.projectId	string	Yes	Microsoft Clarity project ID.
integrations.clearbit.publicApiKey	string	Yes	Clearbit public API key.
integrations.fathom.siteId	string	Yes	Fathom site ID.
integrations.frontchat.snippetId	string (min 6)	Yes	Front chat snippet ID.
integrations.ga4.measurementId	string (must start with G)	Yes	Google Analytics 4 measurement ID.
integrations.gtm.tagId	string (must start with G)	Yes	Google Tag Manager container ID.
integrations.heap.appId	string	Yes	Heap app ID.
integrations.hightouch.writeKey	string	Yes	Hightouch write key.
integrations.hightouch.apiHost	string	No	Hightouch API host.
integrations.hotjar.hjid	string	Yes	Hotjar site ID.
integrations.hotjar.hjsv	string	Yes	Hotjar script version.
integrations.intercom.appId	string (min 6)	Yes	Intercom app ID.
integrations.logrocket.appId	string	Yes	LogRocket app ID.
integrations.mixpanel.projectToken	string	Yes	Mixpanel project token.
integrations.pirsch.id	string	Yes	Pirsch site ID.
integrations.plausible.domain	string	Yes	Plausible domain.
integrations.plausible.server	string	No	Plausible server (self-hosted only).
integrations.posthog.apiKey	string (must start with phc_)	Yes	PostHog API key.
integrations.posthog.apiHost	string (uri)	No	PostHog API host (self-hosted only).
integrations.posthog.sessionRecording	boolean	No	Enable session recording. Default: false.
integrations.segment.key	string	Yes	Segment write key.
integrations.telemetry.enabled	boolean	No	Enable Mintlify telemetry. When false, feedback features are also disabled.
integrations.cookies.key	string	No	Cookie key name.
integrations.cookies.value	string	No	Cookie value.