Skip to main content
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.global
object
Global navigation elements that appear across all pages and locales.
​
navigation.languages
array 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.
​
navigation.versions
array of object
Version switcher for sites with multiple versions.
​
navigation.tabs
array of object
Top-level navigation tabs.
​
navigation.anchors
array of object
Sidebar anchors.
​
navigation.dropdowns
array of object
Dropdowns for grouping related content.
​
navigation.products
array of object
Product switcher for sites with multiple products.
​
navigation.groups
array of object
Groups for organizing content into sections.
​
navigation.pages
array of string or object
Individual pages that make up your documentation.
Type: object Links and buttons displayed in the top navigation bar.
​
navbar.links
array of object
Links to display in the navbar.
​
navbar.primary
object
Primary call-to-action button in the navbar.
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.socials
object
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.links
array of object
Link columns displayed in the footer.
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.content
string
required
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.dismissible
boolean
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.drilldown
boolean
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.options
array
required
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
  • "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
  • "windsurf" — Send the current page to Windsurf
Define custom options as objects:
​
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[].source
string
required
The path to redirect from. Example: /old-page
​
redirects[].destination
string
required
The path to redirect to. Example: /new-page
​
redirects[].permanent
boolean
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.404
object
Settings for the 404 “Page not found” error page.
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, hyphens, and periods.
  • 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.timestamp
boolean
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
}