> ## Documentation Index
> Fetch the complete documentation index at: https://eae70fc-margin.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://eae70fc-margin.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://eae70fc-margin.manicule.dev/docs/api/mcp.
> Every agent surface: https://eae70fc-margin.manicule.dev/docs/.well-known/llms-manifest.json

# Configure your site with docs.json (/docs/settings/docs-json)

<!-- agent-signals: reading_time_min: 12 · est_tokens: 4470 · updated: 2026-11-14 -->
Related: [Migrate from Mintlify](/docs/migrate-from-mintlify.md), [Set logos, favicons, and icons](/docs/customize/branding.md)

# Configure your site with docs.json

Set site identity, rendering, navigation, API documentation, metadata, and behavior with an optional `docs.json` in the documentation-folder root. Use this reference before changing a Mintlify configuration or adding Margin extensions.

## Do this

From the documentation-folder root, create a minimal configuration only if no configuration exists; the command refuses to overwrite an existing file:

```sh
python3 - <<'PY'
import json
from pathlib import Path
path = Path("docs.json")
with path.open("x") as file:
    json.dump({"name": "Acme Docs"}, file, indent=2)
    file.write("\n")
PY
python3 -m json.tool "docs.json" > /dev/null
```

For an existing file, edit only the intended fields and run the syntax check in `Verify`. Syntax validation does not prove Margin compatibility.

## Facts

- `docs.json` is optional; every top-level field is optional. `docs.json` takes precedence over legacy `mint.json`.
- Supported means implemented behavior; Adapted means mapped to Margin's renderer or layout; Ignored means accepted without effect. Unsupported settings produce diagnostics rather than failing publication.
- Nested fields are optional unless identified as required. A light/dark pair contains both `light` and `dark` string values.
- Omitted `colors`, `logo`, and `favicon` permit derivation or detection; explicit `null` disables detection. `x-margin.css: null` disables CSS injection. Other fields must not be assumed nullable.

| Identity field | Type, status, default, and example |
| --- | --- |
| `$schema` | string; Ignored at runtime, editor tooling only; example `https://mintlify.com/docs.json`; can be exposed by `markdown.schema`. |
| `name` | non-empty string; Supported; derived name by default; self-hosted `SITE_NAME` overrides; example `Acme Docs`. |
| `description` | string; Supported; derived page description/excerpt by default; fallback for page/social metadata. |
| `logo` | string, object, or null; Supported; detected by default; object requires `light`, `dark`, optional absolute `href`; null selects text-only chrome. |
| `favicon` | string, light/dark pair, or null; Supported; detected/generated by default; null suppresses favicon link. |

| Appearance field | Type, status, default, and behavior |
| --- | --- |
| `theme` | Adapted enum: `mint`, `linden`, `maple`, `almond`, `palm`, `willow`, `aspen`, `sequoia`, `luma`; omitted layout is `neutral`. |
| Theme layout mapping | `mint`=neutral; `linden`=neutral; `maple`=warm; `almond`=warm; `palm`=verdant; `willow`=verdant; `aspen`=aspen; `sequoia`=dusk; `luma`=contrast. Each theme has its own palette. Layouts approximate Mintlify. |
| `colors` | object or null; Supported; hex-string `primary`, `light`, `dark`; theme-derived tokens and optional logo accent by default; null forces neutral and disables accent derivation. |
| `appearance` | Adapted object; `default`=`system` (default), `light`, or `dark`; boolean `strict` disables theme switching, pins light/dark defaults, and leaves system following the system theme. |
| `background` | Adapted object; no override by default; `color`=hex string or pair; `image`=asset string or pair; `decoration`=`gradient`, `grid`, or `windows`. |
| `fonts` | Adapted object; `family` string, `weight` number, `source` asset string, `format`=`woff` or `woff2`; role objects `heading`, `body`, `mono` accept the same fields; bundled defaults Inter and Geist Mono. |
| `icons.library` | Adapted enum `lucide` (default), `fontawesome`, `tabler`; alternate library matching is best-effort, missing icons fall back with diagnostics. |
| `styling.eyebrows` | Adapted string; default `section`; `breadcrumbs` shows full trail. |
| `styling.latex` | Supported boolean; default false; true compiles with KaTeX. |
| `styling.codeblocks` | Supported string or object; framework highlighting default; `system` follows display mode. Object `theme` is Shiki name or light/dark pair; `languages` is grammar-path string array or `{custom:[paths]}`. |
| `navbar` | Supported object; `links` array entries require `href`, optional `label`/`name`; `primary` requires `href`, optional `type`/`label`; type `button` or `github`; default GitHub link may derive from repository; invalid links dropped independently; placement follows chrome. |
| `footer` | Supported object; `socials` maps platform to URL; `links` array columns require `header`, `items`; items require `label`, `href`; no links by default; invalid items dropped independently. |
| `banner` | Supported object; required non-empty inline-MDX `content`; optional `type`=`info`, `warning`, `critical`, boolean `dismissible`, hex/pair `color`; no banner by default. |

- Non-empty `navigation` replaces filesystem/`meta.json` navigation structure. Omitted pages remain URL-reachable. Frontmatter `hidden: true` hides listed pages. Navigation does not provide access control.

| Navigation field | Entry type and compatibility |
| --- | --- |
| `pages` | Supported array of extensionless page strings, `{href}` links, or group objects. |
| `groups` | Supported array; required `group` string; `pages` defaults to `[]`. |
| `tabs` | Supported array; required `tab` string; external `href` becomes link. |
| `anchors` | Adapted array; required `anchor` string; grouped anchors become roots, link-only anchors become links. |
| `dropdowns` | Supported array; required `dropdown` string; content becomes menu, href-only becomes link. |
| `versions` | Supported array; required `version` string; product-version navigation. |
| `languages` | Supported array; required `language` string; default language unprefixed, other locales prefixed. |
| `products` | Adapted array; required `product` string; optional `name`, `description`; href products are links, containers are menus. |
| `menu` | Supported array; required `item` string; nested navigation children. |
| `global` | Supported object; accepts `languages`, `versions`, `tabs`, `dropdowns`, `anchors`, `products` across sections. |

| Navigation node | Recursive children |
| --- | --- |
| Group | `pages` |
| Tab | `languages`, `versions`, `tabs`, `dropdowns`, `menu`, `groups`, `pages`, `global` |
| Anchor | `languages`, `versions`, `tabs`, `dropdowns`, `groups`, `pages` |
| Dropdown | `languages`, `versions`, `tabs`, `anchors`, `products`, `groups`, `pages` |
| Version | `languages`, `tabs`, `groups`, `pages`, `global` |
| Language | `versions`, `tabs`, `groups`, `pages`, `global` |
| Product | `languages`, `versions`, `tabs`, `anchors`, `groups`, `pages`, `menu`, `global` |
| Menu item | `groups`, `pages`, `tabs`, `dropdowns`, `anchors`, `products`, `versions`, `languages`, `global` |

- Navigation modifiers: string `href` on link-capable nodes; string `icon` on groups/tabs/anchors/dropdowns/products/menu items; boolean `hidden` on containers; boolean `searchable` on groups/tabs; string `root`, boolean `expanded` on groups; string `tag` on groups/versions; boolean `default` on versions/languages. These modifiers are Supported.
- Adapted navigation modifiers: string `directory` on containers (group presentation `accordion`/`card`); hex/pair `color` on anchors/dropdowns/products; tab `align`=`start`/`end` with end ignored. String `description` on dropdowns/products/menu items is Supported. Group numeric `boost` is Ignored; group boolean `public` does not control access.
- Navigation `openapi` is Supported on groups/tabs/anchors/versions/languages/products/menu items; value is source string or `{source,directory}`. `GET /users` beneath an OpenAPI-bearing node resolves to a generated operation page. Explicit navigation hides unreferenced generated sections but preserves URLs and emits `openapi_orphaned`.
- Navigation `sdk` is Adapted for local `{format:"typedoc",source:"reference.json",directory:"sdk"}` artifacts; maximum 500 pages and 30 MB artifact. `docfx`, `javadoc`, `sphinx`, `phpdoc`, and remote SDK sources generate no pages.
- A standalone `{$ref:"./navigation.json"}` node loads in-snapshot JSON; the same reference form works for `redirects`. Limits: 8 nesting levels, 32 expansions, 2 MiB total reference budget. Circular, missing, invalid, or out-of-root references are dropped with diagnostics.

| API field | Type, compatibility, defaults, and constraints |
| --- | --- |
| `api.openapi` | Supported source string, array, or `{source,directory}`; example `openapi.yaml`; overrides convention discovery; navigation owns explicit placement. |
| `openapi` | Supported legacy array of source strings or `{id,spec,label?,path?}`; label defaults `API Reference`, path defaults `api-reference`; id maximum 64, lowercase letters/digits/hyphens, starts alphanumeric; avoid duplicate specs. |
| `api.playground` | Adapted object; display enum `interactive` (default), `simple`, `none`, `auth`; auth behaves as none; proxy boolean default true via `/api/proxy`, restricted to spec servers; credentials boolean default false and effective only with proxy false. |
| `api.params` | Adapted object; expanded enum `all`/`closed`; post string array is Ignored with `unsupported_field`. |
| `api.examples` | Adapted object; languages string array; defaults enum `required`/`all` (default all); autogenerate boolean default true; effective playground prefill always on, authored prefill false unsupported. |
| `api.url` | Adapted string; `full` uses operation servers before path-item servers before root servers, declared variable defaults; relative servers stay relative. |

| Metadata/integration field | Type, compatibility, defaults, and constraints |
| --- | --- |
| `seo.indexing` | Supported enum `navigable` (default)/`all`; sitemap/indexing control. |
| `seo.trailingSlash` | Supported boolean default false; canonical trailing slash. |
| `seo.metatags` | Supported string map; default no extra tags; executable markup rejected, canonical ignored in favor of per-page canonical. |
| `seo.organization` | Supported object; optional non-empty name/legalName max 255; public HTTP(S) url; safe relative/public HTTP(S) logo; public HTTP(S) sameAs array; id ignored. Identity overrides x-margin.seo.publisher. |
| `thumbnails` | Adapted object; image/background asset strings; fonts.family string; appearance derived from background/site when omitted; generated-card default Geist Sans; ingest resolves assets, failures fall back with diagnostics. |
| `integrations.ga4` | Supported object; measurementId string starts `G`. |
| `integrations.posthog` | Supported object; apiKey starts `phc_`; optional apiHost only `https://us.i.posthog.com`, `https://eu.i.posthog.com`, `https://us.posthog.com`, `https://eu.posthog.com`; no paths/query/fragment. |
| `integrations.plausible`, `fathom`, `clarity` | Supported objects with string domain, siteId, projectId respectively; plausible.server ignored. |
| `integrations.amplitude`, `segment`, `intercom` | Supported objects with non-empty string apiKey, key, appId respectively. |
| `integrations.mixpanel` | Supported object; non-empty projectToken; optional region us (default), eu, in. |
| `integrations.hotjar` | Supported object; numeric hjid string/number; optional hjsv string/number defaults 6. |

- Omitted integrations load no providers. Margin-owned loaders use pinned origins. Deployment policy can suppress configured analytics.

| Behavior field | Type, compatibility, defaults, and constraints |
| --- | --- |
| `search.prompt` | Supported string placeholder; backend selected by x-margin.search.mode. |
| `redirects` | Supported array of required source/destination strings, optional permanent boolean default true (308); false gives 307; standalone {$ref} supported. Exact, :param, :param*, *, prefix-* sources; no source queries/fragments; destination query/fragment and captured substitutions allowed; HTTP(S) external destinations allowed; exact matches before patterns, patterns in declaration order. |
| `contextual` | Adapted object; display header (default)/toc; options ordered ID/object array; [] removes menu; unknown IDs omitted. Default IDs copy/view/chatgpt/claude/cursor/t3. Other IDs perplexity/grok/aistudio/devin/windsurf/devin-desktop/devin-mcp/download-spec/download-pdf/github/mcp/add-mcp/vscode. Downloads/GitHub require page resources. |
| `contextual.options` custom objects | Required non-empty title and href; optional description/icon/src strings; href string or {base,query:[{key,value}]}; $page substitutes encoded Markdown, $path page path, $mcp MCP URL; unsafe destinations omitted. |
| `errors.404` | Supported object; redirect boolean true sends unknown paths home; title max 255, description Markdown max 4000; defaults framework 404. |
| `interaction.drilldown` | Adapted boolean default false (expand folder); true navigates first page. |
| `metadata.timestamp` | Supported boolean default false; Git last-modified display; per-page override. |
| `feedback` | Supported booleans thumbsRating/suggestEdit/raiseIssue all default false; edit/issue actions need repository metadata. |
| `variables` | Supported string map; compile-time {{variableName}} substitution, not executable expressions. |
| `variations` | Supported object on every theme; required non-empty options [{id,label}]; strings non-empty; IDs unique, labels case-insensitively unique; first option default; matching View title joins site-wide choice; agent Markdown includes every view in order. |
| `markdown` | Supported object; schema boolean true exposes configured $schema in llms.txt; instructions string/string[] appended to agent outputs including Markdown and MCP reads. |

| x-margin extension | Type, defaults, and constraints (Supported Margin extensions) |
| --- | --- |
| `tokens` | Map token names to strings/light-dark pairs; derived theme defaults; example radius="0.5rem". |
| `css` | String/string[] paths after discovered CSS; null disables CSS injection; stylesheets sanitized. |
| `layout` | CSS dimension strings contentWidth/sidebarWidth/tocWidth/headerHeight; tabMode top/auto; chromeMode band/sidenav; omitted controls derive from theme. |
| `head.meta` | Array of optional name/property and required content strings; no tags by default; inert meta only. |
| `assets.allowExternal` | Host string[] for supported image/font resolution; defaults include fonts.googleapis.com and fonts.gstatic.com; does not authorize scripts. |
| `search.mode` | ai/static/off; ai needs Gateway credentials, self-host without credential stays static; credentials belong in deployment settings. |
| `versions.default` | String product-version default, not deployment commit; example v2. |
| `seo.titleTemplate` | Default `{page} – {site}`; length 1–200, exactly one {page}, at most one {site}, no other brace tokens. |
| `seo.language` | Locale-tag string, derived locale when available; example en-US. |
| `seo.publisher` | Legacy optional type Organization/Person, name/url/logoUrl/sameAs; public HTTP(S) URL restrictions; prefer seo.organization. |
| `seo.provenance` | Required name 1–255 and public HTTP(S) baseUrl without query/fragment; optional license requires name 1–255 and public HTTP(S) url; no provenance by default. |
| `agents` | Booleans contentSignals.search/aiInput/aiTrain default true; indexPreamble/assistantMarkdown default true; markdownFrontmatter default false; mcpInstructions string max 4000 appended to generated instructions, no authored instructions by default. Signals are preferences, not access controls. |

## Not supported

- `public: false` does not make documentation private. Navigation visibility and agent content signals do not restrict access.
- `api.asyncapi`, `api.mdx`, navigation `asyncapi`/`graphql`, `api.params.post`, and authored `api.examples.prefill: false` have no supported implementation.
- `integrations.gtm` (parsed tagId), unknown integration providers, arbitrary script loaders, Plausible custom servers, and non-official PostHog hosts are ignored.
- `banner.contentHast`, `errors.404.descriptionHast`, and error keys other than `404` cannot be authored. `seo.organization.id` does not override generated structured-data IDs.
- `x-margin` extensions are not portable Mintlify settings; theme selection does not provide a custom layout engine.

## Errors

| Identifier | HTTP status | Cause | Fix |
| --- | --- | --- | --- |
| `unknown_field` | Not applicable | Unknown top-level/x-margin key or computed-only field | Remove key or use a documented field. |
| `field_invalid` | Not applicable | Malformed known field/reference | Correct type/value; inspect containing-field fallback. |
| `unsupported_field` | Not applicable | Parsed but inert setting | Remove setting or choose supported behavior. |
| `integration_unsupported` | Not applicable | Unsupported provider, invalid provider ID, or script origin | Use supported provider and admitted data-only fields. |
| `head_rejected` | Not applicable | Unsafe markup in metadata or site-wide canonical | Use inert meta values and per-page canonical behavior. |
| `redirect_invalid` | Not applicable | Invalid pattern/token, loop, or missing internal destination | Correct rule and ensure internal destination exists. |
| `redirect_shadows_page` | Not applicable | Redirect source overlaps a published page | Remove rule or change source. |
| `openapi_orphaned` | Not applicable | Explicit navigation omits generated API section | Reference specification from navigation. |

Invalid JSON fails the build; unsupported-field diagnostics alone do not fail publication.

## Verify

Run from the documentation-folder root to validate JSON syntax:

```sh
python3 -m json.tool "docs.json" > /dev/null
```

Success is exit status `0` with no output. Inspect publication diagnostics to confirm Margin applied the intended fields; syntax validation alone does not check compatibility.

## Related

- [Site configuration](/docs/settings/docs-json)
- [Agent surfaces](/docs/agents/overview)
- [Deployment](/docs/deploy/self-host)