docs.json schema reference

Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site.

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

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

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`
`markdown.schema`	boolean	No	`true`
`markdown.instructions`	string or array of strings	No	None
`seo.indexing`	`"navigable"` \| `"all"`	No	`"navigable"`
`seo.metatags`	object	No	None
`seo.organization`	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.

Example

{
  "navigation": { "$ref": "./navigation.json" }
}

See Split configuration with $ref for more 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})$

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)

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)

`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. Each entry requires a product field and can contain groups, pages, a menu array (same shape as navigation.tabs[].menu, for multi-column product dropdowns), icons, or external links.

Type: array of object—each with: product (string, required), description (string), icon (string), iconType (string), href (string uri), groups (array), pages (array), menu (array)

`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

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 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)

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.

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

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.

docs.json schema reference

On this page