Skip to main content
Every Mintlify site is controlled by a single docs.json file at the root of your repository. This file defines your project name, visual branding, sidebar navigation, API settings, and more. Changes you make here are reflected immediately on your published site.
Every Mintlify site requires a docs.json file at the root of the repository. Without it, your site will not build.

​
Basic setup

Start with the minimum required fields, then add optional settings as you need them.
docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Acme Docs",
  "colors": {
    "primary": "#3B82F6"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "quickstart"]
      }
    ]
  }
}
​
name
string
required
The project name displayed in the browser tab title and the navbar. Choose something short and recognizable.
​
navigation
object
required
Defines the sidebar structure for your docs site. See Navigation for full syntax and examples.

​
Branding

Control how your docs look with logo, favicon, and color settings.
docs.json
{
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg",
    "href": "https://example.com"
  },
  "favicon": "/favicon.ico",
  "colors": {
    "primary": "#3B82F6",
    "light": "#60A5FA",
    "dark": "#1D4ED8"
  }
}
Your site logo. Provide separate images for light and dark mode so the logo stays legible regardless of the user’s theme preference.
​
favicon
string
Path to your favicon image, shown in browser tabs and bookmarks. Accepts a single path string or an object with light and dark variants.
​
colors
object
Brand colors applied across the site for buttons, links, and highlights.
​
modeToggle
object
Controls the light/dark mode toggle in the navbar.
Configure the top navigation bar with links, a primary call-to-action, and optional version or anchor menus.
docs.json
{
  "navbar": {
    "links": [
      { "label": "Community", "href": "https://example.com/community" },
      { "type": "github", "href": "https://github.com/example/repo" }
    ],
    "primary": {
      "type": "button",
      "label": "Get started",
      "href": "https://app.example.com/signup"
    }
  },
  "versions": ["v2", "v1"],
  "anchors": [
    {
      "icon": "book-open",
      "name": "Guides",
      "url": "guides",
      "color": "#3B82F6"
    }
  ]
}
​
navbar
object
Controls the top navigation bar.
​
versions
array
An array of version strings (for example, ["v2", "v1"]) that render a version dropdown in the navbar. Each version should correspond to a matching navigation structure. See the navigation reference for how to define per-version pages.
​
anchors
array
Persistent sidebar links that appear at the top of the navigation panel, above your page groups. Each anchor accepts an icon, name, url, and optional color.

​
API configuration

If your docs include API reference pages, configure your base URL, authentication method, and API playground behavior here.
docs.json
{
  "api": {
    "baseUrl": "https://api.example.com",
    "auth": {
      "method": "bearer",
      "name": "Authorization"
    },
    "playground": {
      "mode": "show"
    }
  },
  "openapi": "openapi.json"
}
​
api
object
Global settings for API documentation and the interactive playground.
​
openapi
string | array
Path or URL to one or more OpenAPI specification files. Mintlify uses this to generate API reference pages and power the playground. Accepts a single path string or an array of paths.
"openapi": ["openapi/v1.json", "openapi/v2.json"]
Add social media links and custom footer navigation to the bottom of every page.
docs.json
{
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "github": "https://github.com/example",
      "linkedin": "https://linkedin.com/company/example"
    }
  }
}
​
footer
object
Footer settings applied to every page.
You can validate your docs.json configuration locally by running mint validate with the Mintlify CLI. Run mint dev to preview all changes before publishing.