Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify-mintlify-improve-search-documentation-53798.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The docs.json file lets you turn a collection of Markdown files into a navigable, customized documentation site. This required configuration file controls styling, navigation, integrations, and more. Think of it as the blueprint for your documentation. Settings in docs.json apply globally to all pages.

​
Setting up your docs.json

To get started, you only need to specify theme, name, colors.primary, and navigation. Other fields are optional and you can add them as your documentation needs grow. For the best editing experience, include the schema reference at the top of your docs.json file. This enables autocomplete, validation, and helpful tooltips in most code editors: 
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your Docs",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // Your navigation structure
  }
  // The rest of your configuration
}

​
Reference

This section contains the full reference for the docs.json file.

​
Customization

​
theme
required
The layout theme of your site.One of the following: mint, maple, palm, willow, linden, almond, aspen.See Themes for more information.
​
name
string
required
The name of your project, organization, or product.
​
colors
object
required
The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements.
​
description
string
Description of your site for SEO and AI indexing.
Set your logo for both light and dark mode.
​
favicon
string or object
Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. Can be a single file or separate files for light and dark mode. Example: /favicon.png
​
thumbnails
object
Thumbnail customization for social media and page previews.
​
styling
object
Visual styling configurations.
​
icons
object
Icon library settings.
​
fonts
object
Set custom fonts for your documentation. The default font varies by theme.
​
appearance
object
Light/dark mode toggle settings.
​
background
object
Background color and decoration settings.

​
Structure

​
navbar
object
Navigation bar items to external links.
​
navigation
object
required
The navigation structure of your content.
​
interaction
object
User interaction settings for navigation elements.
​
metadata
object
Metadata configuration for documentation pages.
​
footer
object
Footer content and social media links.
​
banner
object
Site-wide banner displayed at the top of pages.
​
redirects
array of object
Redirects for moved, renamed, or deleted pages.
​
contextual
object
Contextual menu for AI-optimized content and integrations.

​
API Configurations

​
api
object
API documentation and interactive playground settings.
​
seo
object
SEO indexing configurations.
​
search
object
Search configuration and display settings.

​
Search functionality

Mintlify provides built-in search functionality that automatically indexes all pages in your documentation. The search feature includes:
  • Full-text search - Searches through page titles, descriptions, and content
  • Keyboard shortcuts - Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open search
  • Real-time results - See results as you type
  • Context preview - View snippets of matching content
  • Navigation integration - Search results respect your navigation structure

​
Search indexing

By default, Mintlify indexes all pages included in your navigation configuration. To control which pages are indexed by search engines and included in search results, use the seo.indexing setting: 
"seo": {
  "indexing": "navigable"  // Only index pages in navigation (default)
  // or "all"              // Index all pages including hidden ones
}
Pages marked with noindex: true in their frontmatter are excluded from search engine indexing but may still appear in your site’s internal search.

​
Customizing search appearance

You can customize the search bar placeholder text to provide context-specific guidance: 
"search": {
  "prompt": "Search API docs, guides, and tutorials..."
}

​
Search best practices

  • Use clear, descriptive titles that match what users might search for
  • Write concise descriptions that summarize page content
  • Include relevant keywords naturally in titles and descriptions
  • Keep titles under 60 characters for better display in search results
  • Use descriptive headings that reflect the content below them
  • Break up long content with subheadings
  • Include keywords in the first paragraph of each page
  • Use consistent terminology throughout your documentation
  • Add relevant keywords to page frontmatter: 
    ---
title: "API Authentication"
description: "Learn how to authenticate API requests"
keywords: ["authentication", "API keys", "OAuth", "tokens"]
---
  • Use keywords that match your users’ search intent
  • Include both technical terms and common phrases
  • Place important information near the top of pages
  • Use clear, specific language rather than vague terms
  • Link related pages to help users discover connected content
  • Keep content up-to-date to maintain search relevance

​
Integrations

​
integrations
object
Third-party integrations.

​
Errors

​
errors
object
Error handling settings.

​
Examples

docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. is a company that provides example content and placeholder text.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book",
        "description": "How to use the Example Co. product",
        "groups": [
          {
            "group": "Getting started",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "Customization",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "Billing",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "Changelog",
        "icon": "history",
        "description": "Updates and changes",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Get Started",
      "href": "https://example.com/start"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          {
            "label": "Customers",
            "href": "https://example.com/customers"
          },
          {
            "label": "Enterprise",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "Request Preview",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "Company",
        "items": [
          {
            "label": "Careers",
            "href": "https://example.com/careers"
          },
          {
            "label": "Blog",
            "href": "https://example.com/blog"
          },
          {
            "label": "Privacy Policy",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "contextual": {
    "options": [
      "copy",
      "view",
      "chatgpt",
      "claude"
    ]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "I can't be found",
      "description": "What ever **happened** to this _page_?"
    }
  }
}

​
Upgrading from mint.json

If your docs project uses the deprecated mint.json file, follow these steps to upgrade to docs.json.
1

Install or update the CLI

If you haven’t installed the CLI, install it now:
npm i -g mint
If you already have the CLI installed, make sure it is up to date:
mint update
2

Create your docs.json file

In your docs repository, run:
mint upgrade
This command will create a docs.json file from your existing mint.json. Review the generated file to ensure all settings are correct.
3

Delete your mint.json file

After verifying your docs.json is configured properly, you can safely delete your old mint.json file.