On this page
Configuration overview
What goes in site.json and in project.json, organized by the task you want to do.
docsp reads two kinds of JSON files:
site.json, one per site, next topackage.json: the site name, the list of projects, the portal home, the top bar links, the footer, the languages, the search and the defaults of the theme and code colors.project.json, one per project folder: the project name, its sections, theme, banner, footer, versions, languages, API reference, symbol index and LLM outputs.
Both files are validated against JSON Schemas shipped with the package. An unknown field or a wrong value stops
check and build with the file, the field and the expected value. The
Configuration reference lists every field.
Text in several languages
Fields marked as text take a string, or an object that maps locale codes to strings:
{ "label": { "en": "Guides", "it": "Guide" } }A missing locale falls back to the project's i18n.fallback, then to its i18n.default, then to the first value.
Tasks
Add a project
Add an entry to projects in site.json and create the folder with its project.json. The order of projects is
the order of the portal cards. status adds a Beta or Deprecated badge to the card.
{
"projects": [
{ "path": "rocket" },
{ "path": "comet", "status": "beta" }
]
}Add tabs to a project
Each entry of nav.sections is a tab and a folder of pages. kind decides what else the section contains; see
Project layout.
{
"nav": {
"sections": [
{ "id": "guides", "label": "Guides", "kind": "guides" },
{ "id": "api", "label": "API reference", "kind": "api" },
{ "id": "changelog", "label": "Changelog", "kind": "changelog" }
],
"links": [{ "label": "GitHub", "href": "https://github.com/acme/rocket", "icon": "github" }]
}
}nav.links holds up to four external links for the top bar. The links of site.json show on the portal only; the pages of a
project show the links of its own project.json. With an icon they render as icon buttons.
Set up the portal home
{
"home": {
"title": "Guides and API references for Acme products",
"lead": "Pick a project to get started, or search across all documentation.",
"showReleases": true
}
}showReleases lists the five latest releases of all projects with a changelog section.
Add an edit link
editLink adds an "Edit on GitHub" link (or the name of your host) to the article footer. dir is the folder in the repository that matches
the project's docs/ folder.
{ "editLink": { "repo": "acme/rocket", "branch": "main", "dir": "docs", "host": "github" } }Hosts: github (default), gitlab, codeberg and gitea. For a self-hosted instance, set repo to the full URL.
Ask readers for feedback
feedback.enabled (on by default) shows "Was this page helpful?" under each page. Without feedback.endpoint,
nothing leaves the browser. With an endpoint, the page sends a POST with the page and the answer and confirms only
after a successful response. Set enabled to false to hide the row.
Change the footer
footer.variant is minimal (one row), columns (up to four columns of links) or social (a row of service
icons). legal adds a line such as a copyright notice, and poweredBy: false hides the "Documentation generated
with docsp" line. A project footer replaces the site footer on that project's pages.
Other tasks
- Colors, fonts, logo and banner: Theming.
- Code block colors: Code themes.
- Versions and translations: Versions and languages.
- API pages from OpenAPI: API reference.
- Links from code to symbols: Symbol index.
- Search filters: Search.
- Markdown twins and
llms.txt: LLM outputs.
Accepted but not implemented
analytics (with a provider other than none), nav.cta and api.tryIt pass validation but have no effect. check
and build print a warning for each one that is set.