> ## 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.

# Configuration Reference

Complete reference for every field in the docs.json configuration file with types, defaults, and examples.

## Overview

This page documents every field available in `docs.json`, organized by section. Each entry includes the field path, type, default value, whether it is required, and a description.

For a guided walkthrough of how to use these fields, see [Global Settings](/global-settings). This page is designed as a lookup reference.

---

## Top-Level Fields

These fields sit at the root of your `docs.json` object.

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `$schema` | `string` | -- | No | JSON Schema URL for editor autocompletion |
| `name` | `string` | -- | **Yes** | Project name, shown in browser tab and meta tags |
| `description` | `string` | -- | No | Project description for default meta tags |
| `theme` | `string` | `"mint"` | No | Built-in theme name |
| `logo` | `string \| object` | -- | No | Site logo (see [Logo](#logo)) |
| `favicon` | `string \| object` | -- | No | Browser tab icon (see [Favicon](#favicon)) |

### Accepted `theme` values

`mint` | `maple` | `palm` | `willow` | `linden` | `almond` | `aspen` | `holy` | `atlas` | `nova` | `cipher`

---

## Logo

The `logo` field accepts either a string path or an object that can render an image, text, or both.

**String (image only)**

```json
    { "logo": "/images/logo.svg" }
    ```
    Renders a single image in both modes. Site `name` is used as the `alt` attribute.
  **Image + light/dark**

```json
    {
      "logo": {
        "light": "/images/logo-light.svg",
        "dark": "/images/logo-dark.svg",
        "href": "https://yourcompany.com"
      }
    }
    ```
  **Image + text**

```json
    {
      "logo": {
        "light": "/images/mark-light.svg",
        "dark": "/images/mark-dark.svg",
        "text": true
      }
    }
    ```
    `text: true` reuses your `name` next to the image. Pass a string to override the visible label and the image `alt`.
  **Text only**

```json
    { "logo": { "text": "Acme Docs" } }
    ```
    No image is rendered. The text is shown as the brand wordmark and used for the link's accessible name. Use this when you want a wordmark distinct from `name`.

| Field | Type | Required | Description |
|---|---|---|---|
| `logo` (string) | `string` | -- | Single image path used in both modes. Equivalent to `{ light, dark }` with the same value. |
| `logo.light` | `string` | No | Image shown in light mode. |
| `logo.dark` | `string` | No | Image shown in dark mode. Falls back to `light` if omitted. |
| `logo.text` | `boolean \| string` | No | `true` renders site `name` next to the image. A string overrides the visible label and the `alt` attribute. Defaults to no text. |
| `logo.href` | `string` | No | Click target for the logo. Defaults to the site root (or `basePath` when subfolder hosting is enabled). |

With `text` enabled, the resolved string also becomes the image's `alt` attribute — so a string override (`text: "Acme Docs"`) doubles as accessible labeling.

---

## Favicon

The `favicon` field accepts a string path or an object with light/dark variants.

| Field | Type | Required | Description |
|---|---|---|---|
| `favicon` (string) | `string` | -- | Single favicon path |
| `favicon.light` | `string` | Yes (if object) | Favicon for light mode |
| `favicon.dark` | `string` | Yes (if object) | Favicon for dark mode |

---

## Colors

**Full schema definition**

```typescript
colors: {
  primary: string;    // Required. 6-digit hex, e.g. "#007AFF"
  light?: string;     // Optional. Lighter variant hex
  dark?: string;      // Optional. Darker variant hex
  background?: {
    light?: string;   // Optional. Light mode background hex
    dark?: string;    // Optional. Dark mode background hex
  }
}
```

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `colors.primary` | `string` | -- | **Yes** | `/^#[0-9a-fA-F]{6}$/` | Primary brand color |
| `colors.light` | `string` | Auto | No | 6-digit hex | Lighter variant for hover states |
| `colors.dark` | `string` | Auto | No | 6-digit hex | Darker variant for pressed states |
| `colors.background.light` | `string` | Theme default | No | Any color string | Light mode page background |
| `colors.background.dark` | `string` | Theme default | No | Any color string | Dark mode page background |

---

## Appearance

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `appearance.default` | `string` | `"system"` | No | `system` \| `light` \| `dark` | Initial appearance for first-time visitors |
| `appearance.strict` | `boolean` | `false` | No | -- | Hide the theme toggle and lock to `default` |
| `appearance.animations.enabled` | `boolean` | `true` | No | -- | Master switch for entry animations on rendered pages. |
| `appearance.animations.style` | `string` | `"fadeUp"` | No | `none` \| `fade` \| `fadeUp` \| `slideUp` \| `scale` | Entry-animation style applied to direct children of the page content. |
| `appearance.animations.stagger` | `number` | `40` | No | `0`–`200` (ms) | Delay between each animated section. Set to `0` for a single uniform fade. |

```json
{
  "appearance": {
    "default": "system",
    "animations": {
      "enabled": true,
      "style": "fadeUp",
      "stagger": 40
    }
  }
}
```

Animations are skipped automatically when the visitor has `prefers-reduced-motion: reduce` set, regardless of the `enabled` value. Set `style: "none"` (or `enabled: false`) to opt every visitor out.

Related: [Dark Mode](/dark-mode)

---

## Fonts

**Full schema definition**

```typescript
fonts?: {
  family?: string;      // Global font family (heading + body)
  weight?: string | number;
  source?: string;
  format?: string;
  heading?: {
    family: string;
    weight?: string | number;
    source?: string;
    format?: string;
  };
  body?: {
    family: string;
    weight?: string | number;
    source?: string;
    format?: string;
  };
}
```

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `fonts.family` | `string` | Theme default | No | Global font family (applies to both heading and body) |
| `fonts.weight` | `string \| number` | Theme default | No | Global font weight |
| `fonts.source` | `string` | -- | No | Global font CSS URL |
| `fonts.format` | `string` | -- | No | Global font format hint (e.g. `woff2`) |
| `fonts.heading.family` | `string` | Theme default | No | Heading font family |
| `fonts.heading.weight` | `string \| number` | Theme default | No | Heading font weight |
| `fonts.heading.source` | `string` | -- | No | Heading font CSS URL |
| `fonts.heading.format` | `string` | -- | No | Heading font format hint |
| `fonts.body.family` | `string` | Theme default | No | Body font family |
| `fonts.body.weight` | `string \| number` | Theme default | No | Body font weight |
| `fonts.body.source` | `string` | -- | No | Body font CSS URL |
| `fonts.body.format` | `string` | -- | No | Body font format hint |

---

## Styling

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `styling.eyebrows` | `string` | `"section"` | No | `section` \| `breadcrumbs` | Text above the page title |
| `styling.latex` | `boolean` | `false` | No | -- | Enable LaTeX/KaTeX math rendering |
| `styling.codeblocks` | `string \| object` | `"system"` | No | `system` \| `dark` \| object | Code block color scheme |

### `styling.codeblocks` (object form)

| Field | Type | Description |
|---|---|---|
| `codeblocks.theme` | `string \| { light: string, dark: string }` | Syntax highlighting theme name(s) |
| `codeblocks.languages.custom` | `string[]` | Additional language grammars to load |

---

## Background

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `background.decoration` | `string` | -- | No | `gradient` \| `grid` \| `windows` | Background decoration style |
| `background.color.light` | `string` | Theme default | No | -- | Light mode background color |
| `background.color.dark` | `string` | Theme default | No | -- | Dark mode background color |
| `background.image` | `string \| object` | -- | No | -- | Background image URL or `{ light, dark }` |

---

## Icons

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `icons.library` | `string` | `"lucide"` | No | `fontawesome` \| `lucide` | Icon library used across the site |

---

## Navigation

The `navigation` object defines the entire sidebar and tab structure. See [Navigation Configuration](/navigation-config) for a full guide.

**Full navigation schema**

| Field | Type | Required | Description |
|---|---|---|---|
| `navigation.tabs` | `Tab[]` | No | Array of top-level tabs |
| `navigation.groups` | `Group[]` | No | Array of sidebar groups (flat navigation) |
| `navigation.anchors` | `Anchor[]` | No | Persistent sidebar links to external URLs |
| `navigation.products` | `Product[]` | No | Product switcher entries |
| `navigation.versions` | `Version[]` | No | Version selector entries |
| `navigation.languages` | `Language[]` | No | Language switcher entries |

### Tab

| Field | Type | Required | Description |
|---|---|---|---|
| `tab` | `string` | Yes | Tab label |
| `icon` | `string` | No | Icon next to the label |
| `landing` | `string` | No | Page slug a tab click should navigate to. Overrides the default (first leaf page) and the per-visitor "last visited" memory. |
| `groups` | `Group[]` | Yes | Navigation groups within this tab |

Tab clicks resolve to a real URL in this order: `landing` → the visitor's last-visited page in that tab (stored client-side) → the first leaf page found by walking `groups`. Set `landing` when you want a curated entry page (an overview, a hero) instead of dropping readers into the first sub-page.

### Group

| Field | Type | Required | Description |
|---|---|---|---|
| `group` | `string` | Yes | Group heading |
| `icon` | `string` | No | Icon next to the heading |
| `pages` | `(string \| Group)[]` | Yes | Page paths or nested groups |

### Anchor

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | No | Anchor label |
| `anchor` | `string` | No | Alternative to `name` |
| `url` | `string` | No | Link URL |
| `href` | `string` | No | Alternative to `url` |
| `icon` | `string` | No | Icon name |
| `color` | `string` | No | Accent color |

### Version

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `name` | `string` | -- | Yes | Version label (e.g. `"v2.0"`) |
| `url` | `string` | -- | Yes | URL path prefix |
| `default` | `boolean` | `false` | No | Whether this is the default version |
| `hidden` | `boolean` | `false` | No | Hide from dropdown (still accessible by URL) |
| `lifecycle` | `string` | -- | No | `active` \| `maintenance` \| `deprecated` \| `eol` |
| `sunsetDate` | `string` | -- | No | ISO date for end of life |
| `migrationUrl` | `string` | -- | No | URL to migration guide |
| `deprecationMessage` | `string` | -- | No | Custom deprecation banner message |
| `branch` | `string` | -- | No | Git branch for this version |

### Language (HolyDocs format)

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | `string` | Yes | Language code (e.g. `"en"`) |
| `name` | `string` | Yes | Display name (e.g. `"English"`) |
| `url` | `string` | Yes | URL path prefix |

---

## Navbar

Primary header configuration for top-level links and the main CTA.

| Field | Type | Required | Description |
|---|---|---|---|
| `navbar.links` | `NavbarLink[]` | No | Array of top bar links |
| `navbar.primary` | `object` | No | Primary action button |
| `navbar.primary.type` | `string` | Yes (if set) | `button` \| `github` |
| `navbar.primary.label` | `string` | Yes (if set) | Button text |
| `navbar.primary.href` | `string` | Yes (if set) | Button destination |

### NavbarLink

| Field | Type | Required | Description |
|---|---|---|---|
| `label` | `string` | Yes | Link text |
| `href` | `string` | Yes | Link destination |
| `icon` | `string` | No | Icon name |

---

## Footer

| Field | Type | Required | Description |
|---|---|---|---|
| `footer.socials` | `Record<string, string>` | No | Platform name to URL mapping |
| `footer.links` | `FooterLinkGroup[]` | No | Grouped footer links |
| `footer.text` | `string` | No | Short footer copy such as copyright or legal text |
| `footer.html` | `string` | No | Raw trusted HTML for badges, status links, or compliance snippets |
| `footer.poweredBy` | `boolean` | No | Show the HolyDocs attribution. Defaults to `true` when `footer` is set |

### FooterLinkGroup

| Field | Type | Required | Description |
|---|---|---|---|
| `header` | `string` | No | Group heading |
| `items` | `{ label: string, href: string }[]` | Yes | Links in this group |

---

Use `footer.socials` directly for social icons and `footer.links` for grouped footer columns. Legacy aliases are documented in migration guides only.

`footer.html` is rendered as raw HTML. Only include markup you control.

---

## Banner

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `banner.content` | `string` | -- | Yes (if banner set) | Banner text (supports inline Markdown links) |
| `banner.dismissible` | `boolean` | `true` | No | Allow readers to dismiss the banner |

---

## Search

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `search.prompt` | `string` | -- | No | Prompt text inside the search modal |
| `search.hotkey` | `string` | `"k"` | No | Keyboard shortcut key (with Cmd/Ctrl) |
| `search.placeholder` | `string` | `"Search documentation..."` | No | Search input placeholder text |

---

## SEO

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `seo.indexing` | `string` | `"navigable"` | No | `navigable` \| `all` | Which pages get search engine indexing |
| `seo.noindex` | `boolean` | `false` | No | -- | Add `noindex` to all pages |
| `seo.ogImage` | `string` | Auto-generated | No | -- | Default Open Graph image path |
| `seo.twitterHandle` | `string` | -- | No | -- | Twitter handle for `twitter:site` tag |
| `seo.metatags` | `Record<string, string>` | `{}` | No | -- | Key-value pairs added as `<meta>` tags |

`"navigable"` only indexes pages included in your navigation. `"all"` indexes every MDX file, including orphaned pages not in the sidebar.

---

## API

**Complete API configuration fields**

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `api.openapi` | `string \| string[] \| object` | -- | No | OpenAPI spec source(s) |
| `api.asyncapi` | `string \| string[] \| object` | -- | No | AsyncAPI spec source(s) |
| `api.playground.display` | `string` | `"interactive"` | No | `interactive` \| `simple` \| `none` |
| `api.playground.proxy` | `boolean` | `true` | No | Proxy requests through HolyDocs |
| `api.mdx.auth.method` | `string` | -- | No | `bearer` \| `basic` \| `api_key` \| `oauth2` |
| `api.mdx.auth.name` | `string` | -- | No | Auth header/parameter name |
| `api.mdx.auth.oauth2AuthUrl` | `string` | -- | No | OAuth2 authorization endpoint (valid URL) |
| `api.mdx.auth.oauth2TokenUrl` | `string` | -- | No | OAuth2 token endpoint (valid URL) |
| `api.mdx.auth.oauth2ClientId` | `string` | -- | No | OAuth2 client identifier |
| `api.mdx.auth.oauth2Scopes` | `string` | -- | No | Space-separated OAuth2 scopes |
| `api.mdx.server` | `string \| string[]` | -- | No | Base URL(s) for API requests |
| `api.params.expanded` | `string` | `"closed"` | No | `all` \| `closed` |
| `api.examples.languages` | `string[]` | All | No | Languages for code samples |
| `api.examples.defaults` | `string` | -- | No | `required` \| `all` |
| `api.examples.prefill` | `boolean` | `true` | No | Prefill from spec examples |

### OpenAPI source formats

**Single URL**

```json
    "openapi": "https://api.example.com/openapi.json"
    ```
  **Multiple specs**

```json
    "openapi": ["./specs/v1.json", "./specs/v2.json"]
    ```
  **With directory**

```json
    "openapi": { "source": "https://api.example.com/openapi.json", "directory": "api/ref" }
    ```

Related: [OpenAPI](/openapi) | [API Playground](/api-playground) | [Code Samples](/code-samples)

---

## Assistant

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `assistant.enabled` | `boolean` | `true` | No | -- | Enable the AI chat widget |
| `assistant.name` | `string` | `"AI Assistant"` | No | -- | Name in the chat header |
| `assistant.greeting` | `string` | -- | No | -- | Welcome message |
| `assistant.model` | `string` | `"anthropic/claude-sonnet-4"` | No | See models below | LLM model |
| `assistant.systemPrompt` | `string` | -- | No | Max 2000 chars | Custom system prompt |
| `assistant.suggestedQuestions` | `string[]` | -- | No | Max 4 items | Starter questions |
| `assistant.position` | `string` | `"bottom-right"` | No | `bottom-right` \| `bottom-left` | Widget position |
| `assistant.theme.accentColor` | `string` | Primary color | No | -- | Chat button/header color |
| `assistant.theme.icon` | `string` | `"sparkle"` | No | `sparkle` \| `chat` \| `bot` \| `search` | Trigger icon |
| `assistant.contactSupport.enabled` | `boolean` | `false` | No | -- | Show support fallback |
| `assistant.contactSupport.email` | `string` | -- | No | -- | Support email address |
| `assistant.contactSupport.label` | `string` | `"Contact support"` | No | -- | Support link text |
| `assistant.deflection.enabled` | `boolean` | `false` | No | -- | Enable ticket deflection |
| `assistant.deflection.supportEmail` | `string` | -- | No | Valid email | Deflection email |
| `assistant.deflection.showHelpButton` | `boolean` | `false` | No | -- | Show help button |

### Validated model IDs

| Model | Provider |
|---|---|
| `anthropic/claude-sonnet-4` | Anthropic |
| `anthropic/claude-4-opus` | Anthropic |
| `openai/gpt-4o` | OpenAI |
| `openai/gpt-4o-mini` | OpenAI |
| `x-ai/grok-4.1-fast` | xAI |
| `google/gemini-2.5-flash` | Google |

Other model strings are accepted but not schema-validated.

Related: [AI Assistant](/ai-assistant)

---

## Auth

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `auth.enabled` | `boolean` | `false` | No | -- | Enable site authentication |
| `auth.provider` | `string` | `"better-auth"` | No | `better-auth` \| `custom` | Auth provider |
| `auth.loginUrl` | `string` | -- | No | -- | Redirect URL for unauthenticated users |
| `auth.publicPaths` | `string[]` | -- | No | -- | Paths accessible without auth |
| `auth.jwksUrl` | `string` | -- | No | -- | JWKS endpoint for JWT verification |
| `auth.claimsMapping.groups` | `string` | -- | No | -- | JWT claim path for group membership |
| `auth.claimsMapping.email` | `string` | -- | No | -- | JWT claim path for email |
| `auth.groups` | `Record<string, Group>` | -- | No | -- | Named access groups |
| `auth.groups.<name>.label` | `string` | -- | Yes (if group) | -- | Group display name |
| `auth.groups.<name>.pages` | `string[]` | -- | Yes (if group) | -- | Pages accessible to this group |

Auth-enabled sites skip all page caching (including AI search caching) to prevent content leakage between users. This increases latency compared to public sites.

Related: [SSO](/sso) | [RBAC](/rbac)

---

## Redirects

Each redirect is an object in the `redirects` array.

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `source` | `string` | -- | **Yes** | -- | Path to redirect from (supports `:param` and `*`) |
| `destination` | `string` | -- | **Yes** | -- | Path or URL to redirect to |
| `permanent` | `boolean` | `true` | No | -- | `true` = 301, `false` = 302 |

```json
{
  "redirects": [
    { "source": "/old", "destination": "/new", "permanent": true },
    { "source": "/api/v1/:path*", "destination": "/api/v2/:path*", "permanent": false }
  ]
}
```

---

## Integrations

The `integrations` field is a `Record<string, Record<string, string>>`. Each key is a provider name, and the value is an object of provider-specific configuration.

**All supported integrations and their required fields**

| Provider | Key | Required Fields | Optional Fields |
|---|---|---|---|
| **Google Analytics 4** | `ga4` | `measurementId` | `consentMode` |
| **Google Tag Manager** | `gtm` | `tagId` | -- |
| **PostHog** | `posthog` | `apiKey` | `apiHost` |
| **Segment** | `segment` | `key` | -- |
| **Amplitude** | `amplitude` | `apiKey` | -- |
| **Mixpanel** | `mixpanel` | `projectToken` | -- |
| **Plausible** | `plausible` | `domain` | `server` |
| **Fathom** | `fathom` | `siteId` | -- |
| **Pirsch** | `pirsch` | `id` | -- |
| **Heap** | `heap` | `appId` | -- |
| **Hotjar** | `hotjar` | `hjid` | `hjsv` |
| **Clearbit** | `clearbit` | `publicApiKey` | -- |
| **LogRocket** | `logrocket` | `appId` | -- |
| **Microsoft Clarity** | `clarity` | `projectId` | -- |
| **Hightouch** | `hightouch` | `writeKey` | `apiHost` |
| **Intercom** | `intercom` | `appId` | -- |
| **Front Chat** | `frontchat` | `snippetId` | -- |
| **Osano** | `osano` | `scriptSource` | -- |

Related: [Analytics](/analytics)

---

## Addons

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `addons.feedback.thumbsRating` | `boolean` | `true` | No | -- | Page-level thumbs rating |
| `addons.feedback.editSuggestions` | `boolean` | `false` | No | -- | Suggest-edit button |
| `addons.feedback.raiseIssues` | `boolean` | `false` | No | -- | Report-issue button |
| `addons.ciChecks.brokenLinks` | `string` | `"off"` | No | `off` \| `warning` \| `error` | CI broken link checking |
| `addons.ciChecks.grammarLinter` | `string` | `"off"` | No | `off` \| `warning` \| `error` | CI grammar linting |
| `addons.previews.enabled` | `boolean` | `true` | No | -- | Deploy previews for PRs |

---

## Variables

Each entry in the `variables` array defines a reusable variable.

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `name` | `string` | -- | **Yes** | `/^[a-zA-Z_][a-zA-Z0-9_.]*$/` | Variable identifier |
| `type` | `string` | `"string"` | No | `string` \| `select` \| `secret` \| `computed` | Variable type |
| `label` | `string` | -- | No | -- | Human-readable label |
| `description` | `string` | -- | No | -- | Tooltip text |
| `defaultValue` | `string` | -- | No | -- | Default value |
| `options` | `string[]` | -- | No | -- | Options for `select` type |
| `expression` | `string` | -- | No | -- | Expression for `computed` type |

Usage in MDX: `{{variable.name}}`

---

## Component Theme

Override default component styling across all pages.

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `componentTheme.defaultVariant` | `string` | `"default"` | No | `default` \| `outlined` \| `filled` \| `ghost` | Default component variant |
| `componentTheme.radius` | `string` | -- | No | CSS value | Component border radius |
| `componentTheme.padding` | `string` | -- | No | CSS value | Component padding |
| `componentTheme.border` | `string` | -- | No | CSS value | Component border style |

---

## Thumbnails

Configure auto-generated OG image thumbnails.

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `thumbnails.appearance` | `string` | -- | No | `light` \| `dark` |
| `thumbnails.background` | `string` | -- | No | Background color or gradient |
| `thumbnails.fonts.family` | `string` | -- | No | Font family for thumbnail text |

---

## Contextual

Add context-aware action buttons that appear alongside page content.

| Field | Type | Required | Description |
|---|---|---|---|
| `contextual.options` | `(string \| ContextualOption)[]` | Yes (if set) | Action options |

### ContextualOption (object form)

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | Option title |
| `description` | `string` | Yes | Option description |
| `icon` | `string` | No | Icon name |
| `href` | `string \| object` | Yes | Destination URL or `{ base, query }` object |

---

## Metadata

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `metadata.timestamp` | `boolean` | -- | No | Add last-modified timestamps to pages |

---

## Errors

Customize error page behavior.

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `errors.404.redirect` | `boolean` | -- | No | Auto-redirect 404s to closest match |
| `errors.404.title` | `string` | `"Page not found"` | No | Custom 404 title |
| `errors.404.description` | `string` | -- | No | Custom 404 description |

---

## Hosting

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `hosting.basePath` | `string` | -- | No | `/^\/[a-zA-Z0-9_/-]*$/` | Subfolder path prefix |

Related: [Subfolder Hosting](/subfolder-hosting)

---

## i18n

| Field | Type | Default | Required | Validation | Description |
|---|---|---|---|---|---|
| `i18n.defaultLanguage` | `string` | `"en"` | No | 2-10 chars | Primary language code |
| `i18n.languages` | `string[]` | `[]` | No | 2-10 chars each | Target translation languages |
| `i18n.translationStyle` | `string` | `"formal"` | No | `formal` \| `informal` | Translation tone |
| `i18n.translateCodeComments` | `boolean` | `false` | No | -- | Translate code comments |
| `i18n.blockDeployOnTranslation` | `boolean` | `false` | No | -- | Block deploy until translations complete |

Related: [i18n](/i18n)

---

## Cookie Consent

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `cookieConsent.enabled` | `boolean` | `false` | No | Show consent banner |
| `cookieConsent.position` | `string` | `"bottom"` | No | `bottom` \| `top` |
| `cookieConsent.theme` | `string` | `"light"` | No | `light` \| `dark` |
| `cookieConsent.privacyPolicyUrl` | `string` | -- | No | Valid URL |
| `cookieConsent.categories.essential` | `boolean` | `true` | No | Always enabled |
| `cookieConsent.categories.analytics` | `boolean` | `false` | No | Analytics opt-in default |
| `cookieConsent.categories.functional` | `boolean` | `false` | No | Functional opt-in default |
| `cookieConsent.categories.marketing` | `boolean` | `false` | No | Marketing opt-in default |

---

## Web3

| Field | Type | Required | Description |
|---|---|---|---|
| `web3.walletConnect.projectId` | `string` | Yes (if set) | WalletConnect project ID |
| `web3.walletConnect.chains` | `number[]` | Yes (if set) | Supported chain IDs |
| `web3.walletConnect.defaultChain` | `number` | No | Default chain ID |
| `web3.rpc` | `Record<string, string>` | No | Chain ID to RPC URL mapping |
| `web3.explorer` | `Record<string, string>` | No | Chain ID to block explorer URL |
| `web3.contracts` | `Record<string, Contract>` | No | Named contract definitions |
| `web3.contracts.<name>.address` | `Record<string, string>` | Yes | Chain ID to contract address |
| `web3.contracts.<name>.abi` | `string` | Yes | ABI file path or URL |

---

## Minimal Required Configuration

The absolute minimum `docs.json` requires three things: a name, a primary color, and at least one navigation group.

```json
{
  "name": "My Docs",
  "colors": {
    "primary": "#007AFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction"]
      }
    ]
  }
}
```

Everything else has sensible defaults. Build from this baseline and add configuration as your documentation grows.

---

## Validation

HolyDocs validates your `docs.json` at three points:

**CLI (local)**

Run `holydocs check` to validate your config, check for broken page references, and catch common mistakes before pushing. See [CLI: check](/cli/check).
  **Build (CI)**

The build pipeline validates `docs.json` before processing any content. Invalid configs fail the build with descriptive error messages.
  **Dashboard (GUI)**

The Settings page in the dashboard validates fields in real-time as you edit them, with inline error messages for invalid values.

---

## Related Pages

**[Global Settings](/global-settings)**

Guided walkthrough of every docs.json section with full examples.
  **[Navigation Configuration](/navigation-config)**

Sidebar, tabs, groups, anchors, versions, and languages.
  **[Themes](/themes)**

Visual comparison of all 11 built-in themes.
  **[CLI: check](/cli/check)**

Validate your docs.json locally before deploying.