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

`$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})$

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, fr-CA, he, hi, hu, id, it, ja, jp, ko, lv, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, 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, fr-CA, he, hi, hu, 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 and hyphens only) 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

​$ref

​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

Quick reference

Full property reference

`$ref`

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