Technical documentation teams migrating to or scaling with Mintlify manage site architecture and brand presentation through a single, declarative configuration file: docs.json (formerly mint.json). Rather than maintaining complex routing boilerplate or bespoke CSS stylesheets, Mintlify treats documentation structure as version-controlled data. Teams define global aesthetics, sidebar trees, collapsible nested sections, and multi-domain tab groups in structured JSON alongside their MDX content files.
This guide details how documentation engineers and technical writers configure custom branding, build scalable navigation sidebars, and implement top-level tab groups to support complex, multi-product developer portals.
1. Central Configuration Architecture: The docs.json Blueprint
Every Mintlify site is governed by docs.json located at the root of the repository. While earlier implementations relied on mint.json, the modern docs.json specification unifies layout appearance, navigation hierarchies, API playground behaviors, and third-party integrations into a single schema.
Schema Validation and File Resolution
To enable real-time autocompletion, field validation, and inline documentation in code editors such as VS Code, documentation teams should specify the official JSON schema at the top of docs.json:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme Developer Hub",
"theme": "maple"
}
Key structural conventions in Mintlify include:
- Extensionless File Paths: All file paths declared in navigation arrays refer to
.mdx(or.md) files relative to the repository root without their file extension. For instance,"pages": ["getting-started/quickstart"]resolves to the file located atgetting-started/quickstart.mdx. - Git-Native Collaboration: Because navigation and visual properties are represented in plain JSON, information architecture changes are tracked through standard Git branches, pull requests, and automated deployment previews.
- Web Editor Synchronization: Teams using Mintlify's visual cloud editor can drag and drop pages or adjust sidebar order; edits automatically commit back to
docs.jsonin the connected repository.
2. Configuring Custom Branding and Visual Identity
Mintlify enables teams to align documentation portals with corporate design systems without injecting unmaintainable style overrides. Branding settings reside primarily in top-level fields within docs.json.
Layout Themes
Mintlify provides several built-in layout engines via the theme property. Selecting a theme sets base typography, container widths, sidebar margins, and content padding:
mint: The classic, battle-tested layout suitable for general software documentation.maple: A clean, modern aesthetic favored by SaaS and developer tools.palm: A structured, dense layout tailored for enterprise, fintech, and complex platform documentation.willow: A minimalist, distraction-free reading experience.- Other available themes include
linden,almond,aspen,sequoia, andluma.
Brand Colors and Dark Mode Adaptation
Brand color tokens are declared in the colors object. Mintlify enforces accessible contrast ratios across both light and dark display modes:
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary: The core brand color used for active states, link accents, and prominent buttons in light mode.light: The accent color applied in dark mode for readability against deep background tones.dark: The color applied to hover states and secondary interactive elements across modes.
Dual-Mode Logos and Favicon
To preserve visual clarity across theme switches, teams should provide independent SVG assets for light and dark backgrounds, along with an explicit click-through destination:
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
If logo.href is omitted, clicking the logo defaults to the root landing page of the documentation site.
Typography, Icons, and Background Accents
- Typography: Teams can specify Google Fonts directly by family name (such as
"Inter","Fira Code", or"Playfair Display"), or load self-hosted.woff2files using thefontsobject. Heading and body typefaces can be customized independently. - Icon Libraries: Mintlify natively integrates Font Awesome, Lucide, and Tabler icon libraries through
"icons": { "library": "lucide" }. Individual navigation entries can then reference standard icon names (such as"book-open"or"terminal"), custom SVG definitions, or emojis. - Background Styling: Subtle canvas decorations can be introduced with
"background": { "decoration": "gradient" }or"grid", accompanied by custom light and dark background hex codes. - Theme Enforcement: Teams requiring a fixed look can lock the display mode using
"appearance": { "default": "dark", "strict": true }, which removes the client-side mode toggle.
3. Designing Navigation Sidebars: Groups, Nesting, and Root Pages
The sidebar is the primary vehicle for orienting readers through sequential guides and reference material. Sidebar hierarchies are defined within the navigation object in docs.json.
Basic and Icon-Labeled Groups
A group represents a titled cluster of documentation pages in the sidebar. Each group requires a group name and an array of pages:
"navigation": {
"groups": [
{
"group": "Getting Started",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
Hierarchical Nesting and Default Collapse States
As documentation expands across dozens of sub-topics, flat sidebars become difficult to navigate. Mintlify allows groups to be nested inside the pages array of a parent group.
Teams can manage visual noise by controlling the default expansion state of nested groups using the expanded boolean:
{
"group": "Core Architecture",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "Data Storage",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "Security & Compliance",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
Note: Top-level groups are always expanded by default in the sidebar; the expanded attribute specifically dictates the collapse behavior of nested child groups.
Clickable Group Headers with Root Pages
By default, clicking a group title simply expands or collapses its contents in the sidebar. However, documentation teams often want the group title itself to function as an introductory landing page.
Setting the root property binds an MDX page to the group title:
{
"group": "API Endpoints",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
When a user clicks "API Endpoints" in the sidebar, Mintlify immediately renders api/overview.mdx while revealing the child endpoint pages.
Automated Directory Indexes (directory)
To eliminate the manual upkeep of table-of-contents pages, Mintlify provides the directory attribute for groups that have a declared root page. The platform automatically injects an index of child pages below the root page's markdown body.
Supported values for directory include:
"accordion": Renders child items in collapsible, structured lists."card": Displays child pages as horizontal, clickable cards containing page titles and descriptions."none": Disables directory generation (default).
The directory property is inherited recursively down the navigation subtree, allowing teams to set "directory": "card" on a high-level section and selectively override it with "directory": "none" on technical reference subsets.
4. Segmenting Multi-Product Portals with Tab Groups
For developer platforms that combine conceptual guides, interactive API references, SDK documentation, and release notes, packing everything into a single linear sidebar creates cognitive overload. Tab groups solve this by introducing horizontal top-level navigation.
Site-Level Navigation Tabs
Tabs create distinct operational sections, each with its own dedicated sidebar navigation and isolated URL hierarchy.
Teams define tabs under the navigation.tabs array:
"navigation": {
"tabs": [
{
"tab": "Guides",
"icon": "book-open",
"groups": [
{
"group": "Basics",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "Deployment",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "API Reference",
"icon": "square-terminal",
"groups": [
{
"group": "Endpoints",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "SDKs",
"icon": "code-2",
"groups": [
{
"group": "Client Libraries",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "Community & Changelog",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
When users click between "Guides", "API Reference", and "SDKs" in the top navigation bar:
- The sidebar immediately switches context to display only the groups and pages configured for that specific tab.
- The URL reflects the active section path.
- External destinations (such as
href: "https://changelog.acme.com") launch external resources while remaining visually integrated into the header.
Dropdown Menus Within Tabs
When a single tab encompasses distinct sub-categories or multi-product suites, teams can nest a menu inside the tab configuration:
{
"tab": "Products",
"icon": "layers",
"menu": [
{
"item": "Payments API",
"icon": "credit-card",
"description": "Payment gateway and merchant settlement docs.",
"groups": [
{
"group": "Getting Started",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "Identity Cloud",
"icon": "key-round",
"description": "SSO, OAuth2, and directory sync integrations.",
"groups": [
{
"group": "Authentication",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
Global Anchors vs. Navigation Tabs
Teams should distinguish between top-level tabs and sidebar anchors:
- Tabs (
tabs): Best suited for switching between primary documentation corpora that require distinct sidebars. - Global Anchors (
navigation.global.anchors): Persistent utility links positioned above or below the sidebar (e.g., "API Status", "GitHub Repository", or "Discord Support") that remain visible across all pages and tabs.
Clarifying Site Navigation Tabs vs. In-Page MDX Tabs
A common point of confusion for new teams is the distinction between global navigation tabs in docs.json and in-page <Tabs> components in MDX files:
- Global Navigation Tabs (
docs.json): Architectural site headers that manage routing and sidebar contexts. - MDX
<Tabs>Components: Content-level UI blocks used to display language alternatives (such as switching between cURL, JavaScript, and Python code snippets on a single page). By default, Mintlify synchronizes active tab selections across all<Tabs>components on a page with matching tab labels, unlesssync={false}is explicitly set.
5. Comprehensive Production Example
Below is a complete, production-ready docs.json file illustrating custom brand tokens, multi-tier navigation tabs, nested sidebar groups, clickable root pages, and automated directory card layouts:
{
"$schema": "https://mintlify.com/docs.json",
"name": "CloudScale Documentation",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "System Status",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "Community Slack",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "Product Guides",
"icon": "book-open",
"groups": [
{
"group": "Overview & Setup",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "Infrastructure",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "Networking & DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "API Reference",
"icon": "square-terminal",
"groups": [
{
"group": "Authentication",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "Compute API",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. Team Workflows, Validation, and Operational Best Practices
To maintain high documentation reliability as engineering teams scale, documentation leaders should incorporate the following operational practices:
Local Validation with Mintlify CLI
Never push edits to docs.json blindly. Teams should run the Mintlify CLI locally:
npx mintlify dev
The local server immediately highlights broken links, missing MDX file paths, and syntax discrepancies against the docs.json schema before code reaches production branches.
Preventing Broken Page Paths
Every string inside "pages" must correspond to an existing physical file. If a file is renamed from guides/cli.mdx to guides/cli-tooling.mdx, docs.json must be updated in the same Git commit. Leaving stale paths triggers build warnings and 404 navigation failures.
Maintaining Color Contrast in Dark Mode
When configuring colors.primary, ensure the selected hex code passes WCAG AA contrast against white backgrounds, while colors.light maintains adequate contrast against the default dark mode palette. Neglecting colors.light often leads to washed-out, unreadable navigation links when users switch themes.
Balancing Nesting Depth
Avoid nesting groups more than two levels deep in the sidebar. Deep hierarchies (Group > Subgroup > Sub-subgroup > Page) induce excessive horizontal scrolling and navigation fatigue on mobile devices. When documentation reaches this complexity, promote the subsection to a dedicated tab or dropdown menu.