Skip to content
docsp
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:

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
.
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 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.
↑ ↓ to move↵ to openSearching docsp