> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

**[Navigation](/navigation-config)**

Tabs, nested groups, anchors, versions, languages, and OpenAPI-driven sections.
  **[Site Chrome](/configuration/site-chrome)**

Header links, CTA buttons, banners, footer columns, and social links.
  **[Search & SEO](/configuration/search-and-seo)**

Search prompts, indexing, social cards, metadata, and consent banners.
  **[API Config](/configuration/api-config)**

OpenAPI sources, playground defaults, auth presets, and code examples.
  **[Assistant & AI](/configuration/assistant-and-ai)**

Assistant widget settings, question starters, and AI-aware docs behavior.
  **[Access Control](/configuration/access-control)**

Site auth, public paths, gated groups, claims mapping, and preview behavior.

## Theme and presentation

If you are tuning how the site feels instead of how it behaves, start with these pages:

**[Themes](/themes)**

Theme presets, content width, tone, and visual tradeoffs.
  **[Dark Mode](/dark-mode)**

Appearance defaults, strict modes, and light/dark asset strategy.
  **[Custom CSS](/custom-css)**

Last-mile styling when tokens and themes are not enough.

## Validation workflow

Use this loop whenever you change `docs.json`:

1. Run `holydocs check` locally.
2. Start `holydocs dev` and inspect navigation, header, footer, and search behavior.
3. Click through every tab and nested group to confirm page slugs still resolve.
4. 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.