Configuration Reference

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. This page is designed as a lookup reference.

Top-Level Fields

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

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.

json
{ "logo": "/images/logo.svg" }

json
{  "logo": {    "light": "/images/logo-light.svg",    "dark": "/images/logo-dark.svg",    "href": "https://yourcompany.com"  }}

json
{  "logo": {    "light": "/images/mark-light.svg",    "dark": "/images/mark-dark.svg",    "text": true  }}

json
{ "logo": { "text": "Acme Docs" } }

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.

Colors

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  }}

Appearance

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

Fonts

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;  };}

Styling

styling.codeblocks (object form)

Background

Icons

Navigation

The navigation object defines the entire sidebar and tab structure. See Navigation Configuration for a full guide.

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

Anchor

Version

Language (HolyDocs format)

Navbar

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

NavbarLink

Footer

FooterLinkGroup

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

Search

SEO

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

API

OpenAPI source formats

json
"openapi": "https://api.example.com/openapi.json"

json
"openapi": ["./specs/v1.json", "./specs/v2.json"]

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

Related: OpenAPI | API Playground | Code Samples

Assistant

Validated model IDs

Other model strings are accepted but not schema-validated.

Related: AI Assistant

Auth

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 | RBAC

Redirects

Each redirect is an object in the redirects array.

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.

Related: Analytics

Addons

Variables

Each entry in the variables array defines a reusable variable.

Usage in MDX: {{variable.name}}

Component Theme

Override default component styling across all pages.

Thumbnails

Configure auto-generated OG image thumbnails.

Contextual

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

ContextualOption (object form)

Metadata

Errors

Customize error page behavior.

Hosting

Related: Subfolder Hosting

i18n

Related: i18n

Cookie Consent

Web3

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:

Related Pages