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.

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.

• 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.links (array of object) — Links to display in the navbar.

• navbar.primary (object) — Primary call-to-action button in the navbar.

"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. Maximum 4 columns.

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

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

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.

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.

• 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
• "devin-mcp"—Install your hosted MCP server in Devin
• "download-pdf"—Download the current page as a PDF
• "download-spec"—Download the project'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:

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

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

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.

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

Type: object

Custom error page settings.

• errors.404 (object) — Settings for the 404 "Page not found" error page.

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

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.

"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}}.

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.

"metadata": {
  "timestamp": true
}

• Global settings
• docs.json schema reference
• How to improve documentation SEO