Understanding the docs.json File
Relevant source files
The following files were used as context for generating this wiki page:
The docs.json file is the central configuration for a Mintlify documentation project. It defines the entire structure, navigation, branding, and metadata of the documentation site. The Mintlify CLI tool uses this file as its entry point to render the documentation locally, as indicated by the instruction to run mint dev in the directory where docs.json is located.
This document provides a detailed breakdown of the docs.json schema, explaining each major section and its purpose. All information is derived from the configuration present in the mintlify-docs repository.
Sources: docs.json, README.md:15-19
Core Configuration
The top level of the docs.json file contains essential metadata and branding information for the project.
Sources: docs.json:2-10
| Property | Type | Description | Example Value |
|---|---|---|---|
$schema | string | A URL pointing to the JSON schema for validation and editor autocompletion. | https://mintlify.com/docs.json |
theme | string | Specifies the visual theme of the documentation. | mint |
name | string | The name of the documentation project, displayed prominently. | Mint Starter Kit |
favicon | string | The path to the website's favicon image. | /favicon.svg |
logo | object | Defines paths to the logo for light and dark themes. | { "light": "...", "dark": "..." } |
Theming and Branding
The visual identity of the documentation is controlled by the colors and logo objects.
Sources: docs.json:5-9, docs.json:85-88
Colors
The colors object specifies the primary brand colors used throughout the site.
| Key | Description | Value |
|---|---|---|
primary | The main accent color for buttons and links. | #16A34A |
light | A lighter variant of the primary color. | #07C983 |
dark | A darker variant of the primary color. | #15803D |
Sources: docs.json:5-9
Logo
The logo object provides different logo image files to ensure visibility in both light and dark display modes.
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
}
Sources: docs.json:85-88
Navigation Structure
The navigation object is the most extensive part of docs.json, defining the entire layout of the sidebar and top-level navigation tabs.
The following diagram illustrates the hierarchical structure of the navigation configuration.
This diagram shows how the navigation object contains tabs and global anchors, with tabs further broken down into groups and pages.
Sources: docs.json:11-84
Tabs and Groups
The sidebar navigation is organized into tabs, and each tab contains groups of related pages.
tabs: An array where each object represents a major section of the documentation, like "Guides" or "API reference".groups: Inside each tab, this array organizes pages under a collapsible heading. Each group has agroupname and apagesarray.pages: An array of strings, where each string is a path to a Markdown file (without the.mdextension). For example,"quickstart"maps to thequickstart.mdfile.
Sources: docs.json:12-65, quickstart.md, index.md
Global Anchors
The global.anchors array defines links that appear in a persistent section of the navigation, separate from the main page tree. These are typically used for external resources.
| Property | Description | Example Value |
|---|---|---|
anchor | The visible text label for the link. | Documentation |
href | The URL the link points to. | https://mintlify.com/docs |
icon | An optional icon to display next to the label. | book-open-cover |
Sources: docs.json:66-79
Navbar Links
The navbar object configures links that appear in the top navigation bar of the site. It can contain standard links and a primary call-to-action button.
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:hi@mintlify.com"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://dashboard.mintlify.com"
}
}
Sources: docs.json:89-101
API Reference Integration
The "API reference" tab in the navigation is configured to display API documentation. While some pages are standard Markdown (e.g., api-reference/introduction), the endpoint documentation is typically generated from an OpenAPI specification file, such as api-reference/openapi.json.
The docs.json file defines the navigation structure to these API pages. The Mintlify engine then uses the corresponding OpenAPI file to render detailed interactive documentation for each endpoint.
The diagram below shows the relationship between the user, the documentation site, docs.json, and the openapi.json file.
Sources: docs.json:46-64, api-reference/openapi.json
Additional Features
docs.json also configures smaller, but useful, features for the documentation site.
Contextual Options
The contextual.options array lists features available for code blocks, likely through a context menu. This allows users to interact with code snippets in various ways.
copyviewchatgptclaudeperplexitymcpcursorvscode
Sources: docs.json:102-112
Footer Socials
The footer.socials object provides a simple way to configure social media links that appear in the site's footer.
| Social Network | URL |
|---|---|
x | https://x.com/mintlify |
github | `https://github.com/mintlify%60 |
linkedin | https://linkedin.com/company/mintlify |
Sources: docs.json:113-119
Summary
The docs.json file serves as the blueprint for the entire Mintlify documentation site. It uses a declarative JSON structure to define everything from the project name and color scheme to the deeply nested navigation hierarchy. Its schema allows for clear organization of content pages, integration with API specifications like OpenAPI, and configuration of auxiliary features such as navbar links, contextual code actions, and footer socials. Understanding this file is key to customizing and managing a Mintlify-powered documentation project.