On this page
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:
https://unpkg.com/@fabricators/docsp/schema/site.schema.json
https://unpkg.com/@fabricators/docsp/schema/project.schema.jsonPoint $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. | |
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 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: /<id>/... |
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. | |
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 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/<version>/<locale>/. | |
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 <url>.md |
llm.llmsTxt |
boolean | true |
Writes /<project>/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. | |
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 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. |