docs.json schema reference

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
`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`
`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`
`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.params.expanded`	`"all"` \| `"closed"`	No	`"closed"`
`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`
`api.spec.download`	boolean	No	`false`
`seo.indexing`	`"navigable"` \| `"all"`	No	`"navigable"`
`seo.metatags`	object	No	None
`search.prompt`	string	No	None
`integrations.*`	object	No	None

Full property reference

`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. 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, de, en, es, fr, he, hi, hu, id, it, ja, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, ua, uz, vi, zh, zh-Hans, zh-Hant

`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) 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, de, en, es, fr, he, hi, id, it, ja, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, uz, vi, zh, zh-Hans, zh-Hant Version switcher for multi-version sites. Type: array of object — each with: default (boolean), tag (string) Top-level navigation tabs. Type: array of object — see navigation.global.tabs for shape. Sidebar anchor links. Type: array of object — see navigation.global.anchors for shape. Dropdown menus. Type: array of object — see navigation.global.dropdowns for shape. Product switcher. Type: array of object — see navigation.global.products for shape. Groups for organizing content into labeled sections. Type: array of object Individual pages in your documentation. Type: array of string or object

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

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 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 Link columns in the footer. Type: array of object — 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 Whether to show a dismiss button. Type: boolean Default: false

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

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, hyphens, periods) and values are replacement strings.

`metadata`

Global page metadata settings. Type: object

`metadata.timestamp`

Display a last-modified date on all pages. 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.params`

API parameter display settings. Type: object

`api.params.expanded`

Whether to expand all parameters by default. Type: "all" | "closed" Default: "closed"

`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.spec`

OpenAPI spec display settings. Type: object

`api.spec.download`

Whether to show a download button for the OpenAPI spec on API reference pages. Type: boolean Default: false

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

Get started

Organize

Customize

Create content

Document APIs

Deploy

Optimize

​Quick reference

​Full property reference

​theme - required

​name - required

​colors - required

​colors.primary

​colors.light

​colors.dark

​navigation - required

​navigation.global

navigation.global.tabs

navigation.global.anchors

navigation.global.dropdowns

navigation.global.languages

navigation.global.versions

navigation.global.products

​navigation.languages

​navigation.versions

​navigation.tabs

​navigation.anchors

​navigation.dropdowns

​navigation.products

​navigation.groups

​navigation.pages

​description

​logo

​logo.light

​logo.dark

​logo.href

​favicon

​favicon.light

​favicon.dark

​appearance

​appearance.default

​appearance.strict

​fonts

​fonts.family

​fonts.weight

​fonts.source

​fonts.format

​fonts.heading

​fonts.body

​icons

​icons.library

​background

​background.decoration

​background.color

background.color.light

background.color.dark

​background.image

background.image.light

background.image.dark

​styling

​styling.eyebrows

​styling.latex

​styling.codeblocks

styling.codeblocks.theme

styling.codeblocks.languages

styling.codeblocks.languages.custom

​thumbnails

​thumbnails.appearance

​thumbnails.background

​thumbnails.fonts

thumbnails.fonts.family

​navbar

​navbar.links

​navbar.primary

​footer

​footer.socials

​footer.links

​banner

​banner.content

​banner.dismissible

Quick reference

Full property reference

`theme` - required

`name` - required

`colors` - required

`colors.primary`

`colors.light`

`colors.dark`

`navigation` - required

`navigation.global`

`navigation.global.tabs`

`navigation.global.anchors`

`navigation.global.dropdowns`

`navigation.global.languages`

`navigation.global.versions`

`navigation.global.products`

`navigation.languages`

`navigation.versions`

`navigation.tabs`

`navigation.anchors`

`navigation.dropdowns`

`navigation.products`

`navigation.groups`

`navigation.pages`

`description`

`logo`

`logo.light`

`logo.dark`

`logo.href`

`favicon`

`favicon.light`

`favicon.dark`

`appearance`

`appearance.default`

`appearance.strict`

`fonts`

`fonts.family`

`fonts.weight`

`fonts.source`

`fonts.format`

`fonts.heading`

`fonts.body`

`icons`

`icons.library`

`background`

`background.decoration`

`background.color`

`background.color.light`

`background.color.dark`

`background.image`

`background.image.light`

`background.image.dark`

`styling`

`styling.eyebrows`

`styling.latex`

`styling.codeblocks`

`styling.codeblocks.theme`

`styling.codeblocks.languages`

`styling.codeblocks.languages.custom`

`thumbnails`

`thumbnails.appearance`

`thumbnails.background`

`thumbnails.fonts`

`thumbnails.fonts.family`

`navbar`

`navbar.links`

`navbar.primary`

`footer`

`footer.socials`

`footer.links`

`banner`

`banner.content`

`banner.dismissible`

`interaction`

`interaction.drilldown`

`contextual`

`contextual.options`

`contextual.display`

`redirects`

`variables`