Site structure

Configure navbar, navigation groups, footer links, banner, contextual menu, redirects, and other structural elements in your docs.json file.

Use these settings in your docs.json file to control your site’s information architecture and user experience. Modify the navbar, footer, banners, navigation behavior, contextual menus, redirects, and global content variables.

Settings

Type: object

The navigation structure of your content. This is where you define your site’s full page hierarchy using groups, tabs, dropdowns, anchors, and more.

See Navigation for complete documentation on building your navigation structure.

navigation.globalobject

Global navigation elements that appear across all pages and locales.

Show navigation.global

tabsarray of object

Top-level navigation tabs for organizing major sections. See Tabs.

Show tabs

tabstringrequired

Display name of the tab. Minimum length: 1.

iconstring

The icon to display.

Options:

Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
Lucide icon name, if you have the icons.library property set to lucide in your docs.json
Tabler icon name, if you have the icons.library property set to tabler in your docs.json
URL to an externally hosted icon
Path to an icon file in your project
SVG code wrapped in curly braces

For custom SVG icons:

Convert your SVG using the SVGR converter.
Paste your SVG code into the SVG input field.
Copy the complete <svg>...</svg> element from the JSX output field.
Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
Adjust height and width as needed.

iconTypestring

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

hiddenboolean

Whether to hide this tab by default.

hrefstring (uri)required

URL or path for the tab destination.

anchorsarray of object

Anchored links that appear prominently in the sidebar. See Anchors.

Show anchors

anchorstringrequired

Display name of the anchor. Minimum length: 1.

iconstring

The icon to display.

Options:

Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
Lucide icon name, if you have the icons.library property set to lucide in your docs.json
Tabler icon name, if you have the icons.library property set to tabler in your docs.json
URL to an externally hosted icon
Path to an icon file in your project
SVG code wrapped in curly braces

For custom SVG icons:

Convert your SVG using the SVGR converter.
Paste your SVG code into the SVG input field.
Copy the complete <svg>...</svg> element from the JSX output field.
Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
Adjust height and width as needed.

iconTypestring

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

colorobject

Custom colors for the anchor icon.

Show color

lightstring

Anchor color for light mode. Must be a hex code beginning with #.

darkstring

Anchor color for dark mode. Must be a hex code beginning with #.

hiddenboolean

Whether to hide this anchor by default.

hrefstring (uri)required

URL or path for the anchor destination.

dropdownsarray of object

Dropdown menus for organizing related content. See Dropdowns.

Show dropdowns

dropdownstringrequired

Display name of the dropdown. Minimum length: 1.

iconstring

The icon to display.

Options:

Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
Lucide icon name, if you have the icons.library property set to lucide in your docs.json
Tabler icon name, if you have the icons.library property set to tabler in your docs.json
URL to an externally hosted icon
Path to an icon file in your project
SVG code wrapped in curly braces

For custom SVG icons:

Convert your SVG using the SVGR converter.
Paste your SVG code into the SVG input field.
Copy the complete <svg>...</svg> element from the JSX output field.
Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
Adjust height and width as needed.

iconTypestring

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

hiddenboolean

Whether to hide this dropdown by default.

hrefstring (uri)required

URL or path for the dropdown destination.

languagesarray of object

Language switcher configuration for localized sites. See Languages.

Show languages

language"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fi" | "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"required

Language code in ISO 639-1 format.

defaultboolean

Whether this is the default language.

hiddenboolean

Whether to hide this language option by default.

hrefstring (uri)required

A valid path or external link to this language version of your documentation.

versionsarray of object

Version switcher configuration for multi-version sites. See Versions.

Show versions

versionstringrequired

Display name of the version. Minimum length: 1.

defaultboolean

Whether this is the default version.

hiddenboolean

Whether to hide this version by default.

hrefstring (uri)required

URL or path to this version of your documentation.

productsarray of object

Product switcher for sites with multiple products. See Products.

Show products

productstringrequired

Display name of the product.

descriptionstring

Description of the product.

iconstring

The icon to display.

Options:

Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
Lucide icon name, if you have the icons.library property set to lucide in your docs.json
Tabler icon name, if you have the icons.library property set to tabler in your docs.json
URL to an externally hosted icon
Path to an icon file in your project
SVG code wrapped in curly braces

For custom SVG icons:

Convert your SVG using the SVGR converter.
Paste your SVG code into the SVG input field.
Copy the complete <svg>...</svg> element from the JSX output field.
Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
Adjust height and width as needed.

iconTypestring

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

navigation.languagesarray of object

Language switcher for multi-language sites. Each entry can include language-specific banner, footer, and navbar configurations in addition to the navigation structure.

Show navigation.languages

Language code in ISO 639-1 format.

defaultboolean

Whether this is the default language.

bannerobject

Language-specific banner configuration. Accepts the same options as the top-level banner field.

footerobject

Language-specific footer configuration. Accepts the same options as the top-level footer field.

navbarobject

Language-specific navbar configuration. Accepts the same options as the top-level navbar field.

hiddenboolean

Whether to hide this language option by default.

navigation.versionsarray of object

Version switcher for sites with multiple versions.

Show navigation.versions

defaultboolean

Set to true to make this the default version. If omitted, the first version in the array is the default.

tagstring

Badge label displayed next to the version in the selector. Use to highlight versions such as "Latest", "Recommended", or "Beta".

navigation.tabsarray of object

Top-level navigation tabs.

navigation.anchorsarray of object

Sidebar anchors.

navigation.dropdownsarray of object

Dropdowns for grouping related content.

navigation.productsarray of object

Product switcher for sites with multiple products.

navigation.groupsarray of object

Groups for organizing content into sections.

navigation.pagesarray of string or object

Individual pages that make up your documentation.

navigation.directory"none" | "accordion" | "card"

Directory layout for root pages in navigation groups. When set, groups with a root page automatically display a listing of their children below the page content. Values inherit recursively through the navigation tree. Descendants can override. See Directory listings.

Type: object

Links and buttons displayed in the top navigation bar.

navbar.linksarray of object

Links to display in the navbar.

Show navbar.links

type"github" | "discord"

Optional link type. Omit for a standard text link. Set to github to link to a GitHub repository and show its star count. Set to discord to link to a Discord server and show its online user count.

labelstring

Link text. Required when type is not set. Optional for github and discord. If omitted, Mintlify generates the label from API data.

hrefstring (uri)required

Link destination. Must be a valid external URL. For github, must be a GitHub repository URL. For discord, must be a Discord invite URL.

iconstring

The icon to display.

Options:

Font Awesome icon name, if you have the icons.library property set to fontawesome in your docs.json
Lucide icon name, if you have the icons.library property set to lucide in your docs.json
Tabler icon name, if you have the icons.library property set to tabler in your docs.json
URL to an externally hosted icon
Path to an icon file in your project
SVG code wrapped in curly braces

For custom SVG icons:

Convert your SVG using the SVGR converter.
Paste your SVG code into the SVG input field.
Copy the complete <svg>...</svg> element from the JSX output field.
Wrap the JSX-compatible SVG code in curly braces: icon={<svg ...> ... </svg>}.
Adjust height and width as needed.

iconTypestring

The Font Awesome icon style. Only used with Font Awesome icons.

Options: regular, solid, light, thin, sharp-solid, duotone, brands.

navbar.primaryobject

Primary call-to-action button in the navbar.

Show navbar.primary

type"button" | "github" | "discord"required

Button style. Choose button for a standard button, github for a GitHub repository link with star count, or discord for a Discord invite with online user count.

labelstring

Button text. Required when type is button. Optional for github and discord.

hrefstring (uri)required

Button destination. Must be an external URL. For github, must be a GitHub repository URL. For discord, must be a Discord invite URL.

docs.json

"navbar": {
  "links": [
    { "type": "github", "href": "https://github.com/your-org/your-repo" },
    { "label": "Community", "href": "https://example.com/community" }
  ],
  "primary": {
    "type": "button",
    "label": "Get started",
    "href": "https://example.com/signup"
  }
}

Type: object

Footer content and social media links.

footer.socialsobject

Social media profiles to display in the footer. Each key is a platform name and each value is your profile URL.

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

"socials": {
  "x": "https://x.com/yourhandle",
  "github": "https://github.com/your-org"
}

footer.linksarray of object

Link columns displayed in the footer. Maximum 4 columns.

Show footer.links

headerstring

Column header title. Minimum length: 1.

itemsarray of objectrequired

Links to display in the column.

Show items

labelstringrequired

Link text. Minimum length: 1.

hrefstring (uri)required

Link destination URL.

docs.json

"footer": {
  "socials": {
    "x": "https://x.com/yourhandle",
    "github": "https://github.com/your-org"
  },
  "links": [
    {
      "header": "Company",
      "items": [
        { "label": "Blog", "href": "https://example.com/blog" },
        { "label": "Careers", "href": "https://example.com/careers" }
      ]
    }
  ]
}

Type: object

A site-wide banner displayed at the top of every page.

banner.contentstringrequired

The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.

"content": "We just launched something new. [Learn more](https://example.com)"

banner.dismissibleboolean

Whether to show a dismiss button so users can close the banner. Defaults to false.

docs.json

"banner": {
  "content": "We just launched something new. [Learn more](https://example.com)",
  "dismissible": true
}

`interaction`

Type: object

Controls user interaction behavior for navigation elements.

interaction.drilldownboolean

Controls automatic navigation when selecting a navigation group. Set to true to automatically navigate to the first page when a group expands. Set to false to only expand or collapse the group without navigating. Leave unset to use the theme’s default behavior.

`contextual`

Type: object

The contextual menu gives users quick access to AI tools and page actions. It appears in the page header or table of contents sidebar.

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

contextual.optionsarrayrequired

Actions available in the contextual menu. The first option in the array appears as the default action.

Built-in options:

"add-mcp"—Add your MCP server to the user’s configuration
"aistudio"—Send the current page to Google AI Studio
"assistant"—Open the AI assistant with the current page as context
"copy"—Copy the current page as Markdown to the clipboard
"chatgpt"—Send the current page to ChatGPT
"claude"—Send the current page to Claude
"cursor"—Install your hosted MCP server in Cursor
"devin"—Send the current page to Devin
"devin-mcp"—Install your hosted MCP server in Devin
"download-pdf"—Download the current page as a PDF
"download-spec"—Download the deployment’s OpenAPI specs (single file, or zipped if multiple)
"grok"—Send the current page to Grok
"mcp"—Copy your MCP server URL to the clipboard
"perplexity"—Send the current page to Perplexity
"view"—View the current page as Markdown in a new tab
"vscode"—Install your hosted MCP server in VS Code
"devin-desktop"—Open Devin Desktop with the current page as context

Define custom options as objects:

Show Custom option

titlestringrequired

Display title for the custom option.

descriptionstringrequired

Description text for the custom option.

iconstring

Icon for the custom option. Supports icon library names, URLs, paths, or SVG code.

hrefstring or objectrequired

Link destination. Can be a URL string or an object with base and optional query parameters.

Available placeholder values:

$page—Current page content
$path—Current page path
$mcp—MCP server URL

contextual.display"header" | "toc"

Where to display the contextual options. Choose header to show them in the top-of-page context menu, or toc to show them in the table of contents sidebar. Defaults to header.

docs.json

"contextual": {
  "options": ["copy", "view", "chatgpt", "claude"],
  "display": "header"
}

`redirects`

Type: array of object

Redirects for moved, renamed, or deleted pages. Use these to preserve links when you reorganize your content.

redirects[].sourcestringrequired

The path to redirect from. Example: /old-page

redirects[].destinationstringrequired

The path to redirect to. Example: /new-page

redirects[].permanentboolean

If true, issues a permanent redirect (308). If false, issues a temporary redirect (307). Defaults to true.

docs.json

"redirects": [
  {
    "source": "/old-page",
    "destination": "/new-page"
  },
  {
    "source": "/temp-redirect",
    "destination": "/destination",
    "permanent": false
  }
]

`errors`

Type: object

Custom error page settings.

errors.404object

Settings for the 404 “Page not found” error page.

Show errors.404

redirectboolean

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

titlestring

Custom title for the 404 page.

descriptionstring

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

docs.json

"errors": {
  "404": {
    "redirect": false,
    "title": "Page not found",
    "description": "The page you're looking for doesn't exist. [Go home](/)."
  }
}

`variables`

Type: object

Global variables for use throughout your documentation. Mintlify replaces {{variableName}} placeholders with the defined values at build time.

variables.[variableName]string

A key-value pair where the key is the variable name and the value is the replacement text.

Variable names can contain alphanumeric characters and hyphens.
You must define all variables referenced in your content or the build fails.
Mintlify sanitizes values to prevent XSS attacks.

docs.json

"variables": {
  "version": "2.0.0",
  "api-url": "https://api.example.com"
}

In your content, reference variables with double curly braces:

The current version is {{version}}. Make requests to {{api-url}}.

`metadata`

Type: object

Page-level metadata settings applied globally.

metadata.timestampboolean

Enable a last-modified date on all pages. When enabled, pages display the date the content was last modified. Defaults to false.

You can override this setting on individual pages using the timestamp frontmatter field. See Pages for details.

docs.json

"metadata": {
  "timestamp": true
}

Settings

`navigation` - required

`navbar`

`footer`

`banner`

`interaction`

`contextual`

`redirects`

`errors`

`variables`

`metadata`

On this page