Configure your Mintlify docs site with docs.json

Customize your docs site’s appearance, colors, logo, navbar links, navigation structure, and API playground behavior using the docs.json file.

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

logo · object

Your site logo. Provide separate images for light and dark mode so the logo stays legible regardless of the user’s theme preference.

Show properties

light · string

Path to the logo image used in light mode. Accepts SVG, PNG, or other web-compatible formats.

dark · string

Path to the logo image used in dark mode.

href · string

URL the logo links to when clicked. Typically your marketing site homepage.

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.

Show properties

primary · string · required

The main accent color used for emphasis in light mode. Must be a hex code starting with #.

light · string

Color used for emphasis in dark mode. Defaults to a lighter variant of primary if omitted.

dark · string

Color used for buttons and hover states. Defaults to a darker variant of primary if omitted.

modeToggle · object

Controls the light/dark mode toggle in the navbar.

Show properties

default · string

The default color mode when a user first visits. Accepts "light" or "dark". Defaults to the user’s system preference if omitted.

isHidden · boolean

Set to true to hide the mode toggle and lock the site to the default mode. Useful when your brand requires a single color scheme.

Navigation

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.

Show properties

links · array

Array of link objects displayed in the navbar. Each entry accepts a label and href. Use type: "github" to show a repo with its star count, or type: "discord" to show a server with its online count.

primary · object

A prominent call-to-action button in the navbar. Accepts type ("button", "github", or "discord"), label, and href.

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.

Show properties

baseUrl · string

The base URL prepended to all API endpoint paths in the playground. For example, setting this to https://api.example.com means a GET /users endpoint will send requests to https://api.example.com/users.

auth · object

Authentication settings for the API playground.

Show properties

method · string

The authentication method. Accepts "bearer" (Authorization header), "basic" (username and password), or "key" (custom header or query param).

name · string

The name of the authentication parameter. For "key" auth, this sets the header or query param name used to pass the API key.

playground · object

Controls the interactive API playground displayed on API reference pages.

Show properties

mode · string

How the playground is displayed. Use "show" for the full interactive try-it experience, "simple" to display the request without allowing edits, or "hide" to remove it entirely.

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

Footer and social

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.

Show properties

socials · object

An object mapping social platform keys to their URLs. Mintlify renders the appropriate icon for each platform automatically.

Supported keys: x, github, linkedin, discord, slack, youtube, facebook, instagram, medium, telegram, bluesky, threads, reddit, hacker-news, podcast, website.

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.