docs.json Overview
How to structure docs.json, choose the right config pages, and ship a production-ready HolyDocs site.
What lives in docs.json
docs.json is the control plane for your docs site. It defines navigation, branding, search behavior, AI features, API playground defaults, auth rules, changelog behavior, and deployment-facing settings in one place.
Treat docs.json like application config, not prose content. Keep product copy in MDX pages and keep site behavior in docs.json.
Start from a minimal config
json{ "name": "Acme Docs", "theme": "holy", "colors": { "primary": "#FBBF24" }, "navigation": { "groups": [ { "group": "Getting Started", "pages": ["introduction", "quickstart"] } ] }}
That gets a site online. Most teams then expand docs.json in four passes:
Information architecture
Build navigation first. Decide tabs, groups, nested groups, versions, and language selectors before polishing visuals.
Brand and chrome
Add logo, favicon, fonts, background, navbar, and footer so the site feels owned rather than template-default.
Product features
Layer in api, assistant, search, changelog, auth, and add-ons once the core docs are stable.
Governance
Add redirects, preview rules, cookie consent, integrations, and validation checks before scaling content.
Production example
json{ "name": "Acme Platform Docs", "description": "Docs for Acme APIs, SDKs, and deployment workflows.", "theme": "holy", "colors": { "primary": "#FBBF24", "light": "#FCD34D", "dark": "#D97706" }, "appearance": { "default": "system" }, "background": { "decoration": "grid", "color": { "light": "#F7F4EA", "dark": "#060606" } }, "navigation": { "tabs": [ { "tab": "Docs", "groups": [ { "group": "Getting Started", "pages": ["introduction", "quickstart"] }, { "group": "API", "pages": ["api", "api/authentication"] } ] } ], "anchors": [ { "name": "Dashboard", "url": "https://app.example.com", "icon": "layout-dashboard" } ] }, "navbar": { "links": [ { "label": "Pricing", "href": "https://example.com/pricing" }, { "label": "GitHub", "href": "https://github.com/example", "icon": "github" } ], "primary": { "type": "button", "label": "Start Free", "href": "https://app.example.com/signup" } }, "footer": { "text": "Copyright 2026 Example Inc.", "html": "<a href=\"https://status.example.com\">System status</a>", "socials": { "github": "https://github.com/example", "discord": "https://discord.gg/example" } }}
Choose the right page
Theme and presentation
If you are tuning how the site feels instead of how it behaves, start with these pages:
Validation workflow
Use this loop whenever you change docs.json:
- Run
holydocs checklocally. - Start
holydocs devand inspect navigation, header, footer, and search behavior. - Click through every tab and nested group to confirm page slugs still resolve.
- Deploy a preview before merging any IA change that moves or renames pages.
docs.json is most effective when it stays opinionated. Prefer a few clear tabs with nested groups over dozens of top-level groups competing for attention.