# Configuration reference

Every field of site.json and project.json, with its type, default and meaning.

Generated from the JSON Schemas by `pnpm --filter @fabricators/docsp docs:config`. Do not edit by hand.

The schemas are published with the package and at:

```text
https://unpkg.com/@fabricators/docsp/schema/site.schema.json
https://unpkg.com/@fabricators/docsp/schema/project.schema.json
```

Point `$schema` at them (or at `node_modules/@fabricators/docsp/schema/`) for editor completion. The build rejects
a file that does not match, naming the field and the expected value.

A *text* value is a string or an object that maps locale codes to strings, for example `{ "it": "Guide", "en": "Guides" }`.

## site.json

One file for the portal that groups the projects. Each project has its own project.json.

| site.json field | Type | Default | Description |
|---|---|---|---|
| `name` | string | required | Site name, shown next to the logo. |
| `url` | string |  | Public base URL, used for canonical links. |
| `logo` | object |  | Logo shown in the square of the mark. |
| `logo.light` | string |  | Image file for light mode, relative to site.json (SVG recommended). Replaces the letters of the mark in the top bar square. |
| `logo.dark` | string |  | Image file for dark mode. Without it the light image is used in both modes. |
| `logo.mark` | string |  | Without a logo image: one or two letters shown in the square. |
| `theme` | object |  | Theme axes. See the theme definition below. |
| `theme.accent` | `"indigo"` \| `"teal"` \| `"orange"` \| `"graphite"` or hex color |  | A preset or a hex color. The build picks the text color on it (white or #1b1b1a) for light and dark mode separately and passes both to the page as --on-accent-light and --on-accent-dark. With a custom color the build fails below 4.5:1. |
| `theme.accentDark` | hex color |  | Color for dark mode. Defaults to accent, after the same contrast check. |
| `theme.mode` | `"light"` \| `"dark"` \| `"system"` | `"system"` | Default color mode. Readers can switch it; their choice is saved. |
| `theme.grays` | `"warm"` \| `"cool"` \| `"neutral"` | `"warm"` | Gray scale. |
| `theme.headings` | `"geist"` \| `"instrument-serif"` \| `"space-grotesk"` or object |  | Heading font: a bundled one or { family, src, weight }. |
| `theme.radius` | `"sharp"` \| `"standard"` \| `"soft"` | `"standard"` | Corner radius scale. |
| `theme.header` | `"neutral"` \| `"tinted"` \| `"solid"` | `"neutral"` | neutral, tinted (project color at 9% on the surface) or solid (project color, text in on-accent). |
| `theme.code` | `"dark"` \| `"light"` | `"dark"` | Code block colors. |
| `theme.css` | string |  | Escape hatch: a CSS file, relative to the file that declares it, with :root or html rules that only redefine --* custom properties. The build fails on any other selector or declaration. |
| `projects` | array of object | required | Projects in portal order. |
| `projects[].path` | string | required | Folder that contains project.json and the content. |
| `projects[].status` | `"stable"` \| `"beta"` \| `"deprecated"` | `"stable"` | beta and deprecated projects show a badge on their portal card. |
| `home` | object |  | Portal home page. |
| `home.title` | text (string or {locale: string}) |  | Plain text, or an object mapping locale code to text. |
| `home.lead` | text (string or {locale: string}) |  | Plain text, or an object mapping locale code to text. |
| `home.showReleases` | boolean | `true` | Shows the latest releases table. |
| `nav` | object |  | Navigation in the top bar. |
| `nav.links` | array of object |  | Up to four external links in the top bar. With an icon they render as icon buttons. |
| `nav.links[].label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `nav.links[].href` | string | required | Link target. |
| `nav.links[].icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `footer` | object |  | Page footer. |
| `footer.variant` | `"minimal"` \| `"columns"` \| `"social"` | `"minimal"` | minimal (one row), columns (up to four link columns) or social (icon row). |
| `footer.columns` | array of object |  | Link columns for the columns variant. |
| `footer.columns[].title` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `footer.columns[].links` | array of object | required | Links in the column. |
| `footer.columns[].links[].label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `footer.columns[].links[].href` | string | required | Link target. |
| `footer.columns[].links[].icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `footer.social` | array of object |  | Icon links for the social variant. |
| `footer.social[].type` | `"github"` \| `"gitlab"` \| `"codeberg"` \| `"linkedin"` \| `"mastodon"` \| `"bluesky"` \| `"x"` \| `"youtube"` \| `"discord"` \| `"rss"` \| `"email"` | required | Service, used for the icon and the accessible name. |
| `footer.social[].href` | string | required | Link target. |
| `footer.legal` | text (string or {locale: string}) |  | Plain text, or an object mapping locale code to text. |
| `footer.poweredBy` | boolean | `true` | Shows "Documentation generated with docsp". |
| `i18n` | object |  | Locales of the interface and the content. |
| `i18n.default` | string | required | Locale served without a URL prefix. |
| `i18n.fallback` | string |  | Locale used to open a page that is not translated. |
| `i18n.locales` | array of object | required | Every locale the site or project offers. |
| `i18n.locales[].code` | string | required | Locale code, for example it or pt-BR. |
| `i18n.locales[].label` | string | required | Language name in the language itself: English, Deutsch. |
| `i18n.locales[].status` | `"complete"` \| `"partial"` | `"complete"` | partial shows the Partial badge in the language menu. |
| `search` | object |  | Search settings. |
| `search.crossProject` | boolean | `true` | Offers the All projects filter in the search dialog. |
| `analytics` | object |  | Not implemented yet: with a provider other than none the build prints a warning and adds no script. No external request is made. |
| `analytics.provider` | `"none"` \| `"plausible"` \| `"umami"` \| `"custom"` | `"none"` | none, plausible, umami or custom. |
| `analytics.src` | string |  | Script URL of the provider. |
| `analytics.domain` | string |  | Site identifier for the provider. |
| `redirects` | array of object |  | Redirect pages written at build time (meta refresh). |
| `redirects[].from` | string | required | Old path. |
| `redirects[].to` | string | required | New path or URL. |
| `redirects[].status` | `301` \| `302` \| `308` | `301` | Reserved for hosts that support status codes; static output uses a meta refresh. |
| `code` | object |  | Code blocks, the default of projects that set none. |
| `code.theme` | `"docsp"` \| `"catppuccin"` \| `"github"` \| `"one"` \| `"solarized"` \| `"rose-pine"` \| `"gruvbox"` \| `"dracula"` \| `"nord"` \| `"tokyo-night"` | `"docsp"` | Code color theme: docsp (the design's colors, see theme.code), or a family with a light and a dark member (catppuccin, github, one, solarized, rose-pine, gruvbox); dracula, nord and tokyo-night are dark in both modes. Visitors can pick another one from the top bar. |
| `code.mode` | `"auto"` \| `"light"` \| `"dark"` | `"auto"` | Code block mode: auto follows the page's light or dark mode; light or dark fixes it, for example dark code on a light page. Dark-only themes ignore light. Visitors can change it from the top bar. |

## project.json

One project.json per project, in the project folder listed in site.json.

| project.json field | Type | Default | Description |
|---|---|---|---|
| `id` | string | required | Used in URLs: /&lt;id&gt;/... |
| `name` | string | required | Project name, shown in the selector, tabs and portal card. |
| `tagline` | text (string or {locale: string}) |  | Short line under the name in the portal and the project selector (at most 80 characters). |
| `description` | text (string or {locale: string}) |  | One sentence for the portal card: what the project does and for whom. |
| `logo` | object |  | Logo shown in the square of the mark. |
| `logo.light` | string |  | Image file for light mode, relative to project.json (SVG recommended). Replaces the letters of the mark in the project selector, portal card and footer. |
| `logo.dark` | string |  | Image file for dark mode. Without it the light image is used in both modes. |
| `logo.mark` | string |  | Without a logo: one or two letters shown in the square in the project color. |
| `theme` | object |  | Theme axes. See the theme definition below. |
| `theme.accent` | `"indigo"` \| `"teal"` \| `"orange"` \| `"graphite"` or hex color |  | A preset or a hex color. The build picks the text color on it (white or #1b1b1a) for light and dark mode separately and passes both to the page as --on-accent-light and --on-accent-dark. With a custom color the build fails below 4.5:1. |
| `theme.accentDark` | hex color |  | Color for dark mode. Defaults to accent, after the same contrast check. |
| `theme.mode` | `"light"` \| `"dark"` \| `"system"` | `"system"` | Default color mode. Readers can switch it; their choice is saved. |
| `theme.grays` | `"warm"` \| `"cool"` \| `"neutral"` | `"warm"` | Gray scale. |
| `theme.headings` | `"geist"` \| `"instrument-serif"` \| `"space-grotesk"` or object |  | Heading font: a bundled one or { family, src, weight }. |
| `theme.radius` | `"sharp"` \| `"standard"` \| `"soft"` | `"standard"` | Corner radius scale. |
| `theme.header` | `"neutral"` \| `"tinted"` \| `"solid"` | `"neutral"` | neutral, tinted (project color at 9% on the surface) or solid (project color, text in on-accent). |
| `theme.code` | `"dark"` \| `"light"` | `"dark"` | Code block colors. |
| `theme.css` | string |  | Escape hatch: a CSS file, relative to the file that declares it, with :root or html rules that only redefine --* custom properties. The build fails on any other selector or declaration. |
| `nav` | object |  | Navigation in the top bar. |
| `nav.sections` | array of object |  | Tabs of the project. Each id is a folder under docs/&lt;version&gt;/&lt;locale&gt;/. |
| `nav.sections[].id` | string | required | Folder and URL segment of the section. |
| `nav.sections[].label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `nav.sections[].kind` | `"guides"` \| `"api"` \| `"sdk"` \| `"changelog"` \| `"custom"` |  | guides, api (adds OpenAPI pages), sdk, changelog (reads changelog/) or custom. |
| `nav.links` | array of object |  | Up to four external links in the top bar. With an icon they render as icon buttons. |
| `nav.links[].label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `nav.links[].href` | string | required | Link target. |
| `nav.links[].icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `nav.cta` | object |  | Not implemented yet: accepted, the build prints a warning and nothing is shown. |
| `nav.cta.label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `nav.cta.href` | string | required | Link target. |
| `nav.cta.icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `banner` | object |  | Announcement above the top bar. |
| `banner.id` | string | required | Change the id to show the banner again to readers who dismissed it. |
| `banner.variant` | `"accent"` \| `"neutral"` \| `"warning"` | required | accent for releases, neutral for events, warning for breaking changes (cannot be dismissed). |
| `banner.text` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `banner.link` | object |  | Optional link after the text. |
| `banner.link.label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `banner.link.href` | string | required | Link target. |
| `banner.link.icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `banner.tag` | text (string or {locale: string}) |  | Plain text, or an object mapping locale code to text. |
| `banner.dismissible` | boolean | `true` | Shows the close button. A dismissed banner stays hidden for its id. |
| `banner.until` | string (date) |  | The banner is hidden after this date (YYYY-MM-DD). |
| `footer` | object |  | Page footer. |
| `footer.variant` | `"minimal"` \| `"columns"` \| `"social"` | `"minimal"` | minimal (one row), columns (up to four link columns) or social (icon row). |
| `footer.columns` | array of object |  | Link columns for the columns variant. |
| `footer.columns[].title` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `footer.columns[].links` | array of object | required | Links in the column. |
| `footer.columns[].links[].label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `footer.columns[].links[].href` | string | required | Link target. |
| `footer.columns[].links[].icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
| `footer.social` | array of object |  | Icon links for the social variant. |
| `footer.social[].type` | `"github"` \| `"gitlab"` \| `"codeberg"` \| `"linkedin"` \| `"mastodon"` \| `"bluesky"` \| `"x"` \| `"youtube"` \| `"discord"` \| `"rss"` \| `"email"` | required | Service, used for the icon and the accessible name. |
| `footer.social[].href` | string | required | Link target. |
| `footer.legal` | text (string or {locale: string}) |  | Plain text, or an object mapping locale code to text. |
| `footer.poweredBy` | boolean | `true` | Shows "Documentation generated with docsp". |
| `versions` | object |  | Documentation versions. |
| `versions.current` | string | required | Version served without a URL segment. |
| `versions.list` | array of string | required | Every version, newest first, in the order of the version control. |
| `versions.deprecated` | array of string |  | Pages of these versions show the warning banner, which cannot be dismissed. |
| `i18n` | object |  | Locales of the interface and the content. |
| `i18n.default` | string | required | Locale served without a URL prefix. |
| `i18n.fallback` | string |  | Locale used to open a page that is not translated. |
| `i18n.locales` | array of object | required | Every locale the site or project offers. |
| `i18n.locales[].code` | string | required | Locale code, for example it or pt-BR. |
| `i18n.locales[].label` | string | required | Language name in the language itself: English, Deutsch. |
| `i18n.locales[].status` | `"complete"` \| `"partial"` | `"complete"` | partial shows the Partial badge in the language menu. |
| `llm` | object |  | Markdown versions for language models. |
| `llm.copyButton` | boolean | `true` | Shows the Copy for LLM button. |
| `llm.markdownRoutes` | boolean | `true` | Every page is also served as &lt;url&gt;.md |
| `llm.llmsTxt` | boolean | `true` | Writes /&lt;project&gt;/llms.txt. |
| `editLink` | object |  | Edit link in the article footer. |
| `editLink.repo` | string | required | Repository as owner/name, or a full URL for self-hosted Gitea. |
| `editLink.branch` | string | `"main"` | Branch to edit. |
| `editLink.dir` | string | `"docs"` | Folder in the repository that matches the project docs/ folder. |
| `editLink.host` | `"github"` \| `"gitlab"` \| `"codeberg"` \| `"gitea"` | `"github"` | Code host. |
| `feedback` | object |  | Was this page helpful? row. |
| `feedback.enabled` | boolean | `true` | Shows the feedback buttons. |
| `feedback.endpoint` | string |  | URL that receives a POST with the page and the answer. Without it nothing leaves the browser. |
| `api` | object |  | API reference generated from OpenAPI. |
| `api.openapi` | string | required | Path of the OpenAPI 3.x file (YAML or JSON), relative to the project folder. |
| `api.languages` | array of string | `["curl"]` | Request samples to generate: curl, go, typescript. |
| `api.tryIt` | boolean | `false` | Not implemented yet: accepted, the build prints a warning. Requests from the page are not supported. |
| `search` | object |  | Search settings. |
| `search.scope` | `"project"` \| `"site"` | `"project"` | project preselects the current project in the search filters, site preselects all projects. |
| `symbols` | object |  | Links code to the symbols a compiler resolved, from indexes made by the project's CI. |
| `symbols.repo` | string | required | Repository URL used in source links, for example https://github.com/owner/name. |
| `symbols.commit` | string | required | Full commit hash the indexes were made from. The build fails when the source checkout is at another commit, or when a file it reads is not in that commit or has uncommitted changes. "auto" takes the checkout's HEAD and skips these checks: use it only for example sites. |
| `symbols.sourceRoot` | string | required | Top folder of the source checkout, relative to the project folder. Paths from the indexes, after pathPrefix, are relative to it, as are the paths in source links. |
| `symbols.sourceLink` | string | `"{repo}/blob/{commit}/{path}#L{line}"` | Source link template with {repo}, {commit}, {path} and {line}. Links to a whole file drop the part from the character before {line}. |
| `symbols.strict` | boolean | `false` | Fail the build, instead of warning, when a name in a hand-written code block matches more than one symbol. |
| `symbols.indexes` | array of object | required | Index files the project's CI produced. docsp reads them and never runs a compiler. |
| `symbols.indexes[].type` | `"scip"` \| `"nm"` \| `"tla"` | required | scip: SCIP index (scip-clang, rust-analyzer). nm: folder or files of nm -P output, one per object. tla: SANY XML exports. |
| `symbols.indexes[].paths` | array of string | required | Index files or folders, relative to the project folder. |
| `symbols.indexes[].pathPrefix` | string |  | Prepended to the paths found in the index to make repository paths: the SCIP project root, the folder of the TLA+ modules, or the build tree root for nm. |
| `code` | object |  | Code blocks. |
| `code.theme` | `"docsp"` \| `"catppuccin"` \| `"github"` \| `"one"` \| `"solarized"` \| `"rose-pine"` \| `"gruvbox"` \| `"dracula"` \| `"nord"` \| `"tokyo-night"` | `"docsp"` | Code color theme: docsp (the design's colors, see theme.code), or a family with a light and a dark member (catppuccin, github, one, solarized, rose-pine, gruvbox); dracula, nord and tokyo-night are dark in both modes. Visitors can pick another one from the top bar. |
| `code.mode` | `"auto"` \| `"light"` \| `"dark"` | `"auto"` | Code block mode: auto follows the page's light or dark mode; light or dark fixes it, for example dark code on a light page. Dark-only themes ignore light. Visitors can change it from the top bar. |

## Shared definitions

### theme

Used by `site.json` (defaults for every project) and `project.json`. Project values win.

| theme field | Type | Default | Description |
|---|---|---|---|
| `accent` | `"indigo"` \| `"teal"` \| `"orange"` \| `"graphite"` or hex color |  | A preset or a hex color. The build picks the text color on it (white or #1b1b1a) for light and dark mode separately and passes both to the page as --on-accent-light and --on-accent-dark. With a custom color the build fails below 4.5:1. |
| `accentDark` | hex color |  | Color for dark mode. Defaults to accent, after the same contrast check. |
| `mode` | `"light"` \| `"dark"` \| `"system"` | `"system"` | Default color mode. Readers can switch it; their choice is saved. |
| `grays` | `"warm"` \| `"cool"` \| `"neutral"` | `"warm"` | Gray scale. |
| `headings` | `"geist"` \| `"instrument-serif"` \| `"space-grotesk"` or object |  | Heading font: a bundled one or { family, src, weight }. |
| `radius` | `"sharp"` \| `"standard"` \| `"soft"` | `"standard"` | Corner radius scale. |
| `header` | `"neutral"` \| `"tinted"` \| `"solid"` | `"neutral"` | neutral, tinted (project color at 9% on the surface) or solid (project color, text in on-accent). |
| `code` | `"dark"` \| `"light"` | `"dark"` | Code block colors. |
| `css` | string |  | Escape hatch: a CSS file, relative to the file that declares it, with :root or html rules that only redefine --* custom properties. The build fails on any other selector or declaration. |

### link

| link field | Type | Default | Description |
|---|---|---|---|
| `label` | text (string or {locale: string}) | required | Plain text, or an object mapping locale code to text. |
| `href` | string | required | Link target. |
| `icon` | string |  | Lucide icon name, or github, gitlab, linkedin, youtube. |
