docs.json

Every Holocron site needs a config file at the project root. Holocron supports three filenames (first found wins):

docs.json (preferred)
docs.jsonc (supports // comments)
holocron.jsonc (legacy Holocron name, also supports comments)

All three follow the same schema, which is compatible with Mintlify's docs.json for the fields Holocron consumes.

Minimal config

123456789{
  "name": "My Docs",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "quickstart"]
    }
  ]
}

Full config reference

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152{
  "$schema": "https://unpkg.com/@holocron.so/vite/src/schema.json",
  "name": "My Docs",
  "description": "Documentation for my project",
  "colors": { "primary": "#6366f1" },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  },
  "favicon": "/favicon.svg",
  "appearance": { "default": "system" },
  "fonts": { "family": "Inter" },
  "icons": { "library": "lucide" },
  "navbar": {
    "links": [
      { "type": "github", "href": "https://github.com/example/docs" }
    ]
  },
  "banner": {
    "content": "New: [v2.0 is out](/changelog)",
    "dismissible": true
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          { "group": "Getting Started", "pages": ["index", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  },
  "footer": {
    "socials": {
      "github": "https://github.com/example",
      "x": "https://x.com/example",
      "discord": "https://discord.gg/example"
    }
  },
  "redirects": [
    { "source": "/old", "destination": "/new" }
  ],
  "search": { "prompt": "Search docs..." },
  "seo": {
    "metatags": { "author": "My Company" }
  },
  "assistant": { "enabled": true }
}

Schema autocomplete

Point your editor at the JSON Schema for autocomplete and validation:

123{
  "$schema": "https://unpkg.com/@holocron.so/vite/src/schema.json"
}

The schema is generated from the Zod definitions in vite/src/schema.ts.

Passthrough behavior

Holocron's schema accepts unknown fields. Any fields from Mintlify that Holocron does not consume, like integrations, analytics, or api.playground, are accepted without errors and ignored at runtime. This means you can usually use a Mintlify docs.json without stripping unknown fields.

Config normalization

Holocron normalizes shorthand forms into a consistent internal shape:

logo: "/logo.svg" becomes { light: "/logo.svg" } and is rendered for both modes unless dark is provided
favicon: "/favicon.svg" becomes { light: "/favicon.svg", dark: "/favicon.svg" }
navigation: a flat array of groups is wrapped in a default tab
colors: missing light or dark values fall back from primary when styles are generated
products: normalized into dropdowns at config time