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

JSON
{ "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.

JSONsite.json
{
  "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.

JSONproject.json
{
  "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

JSONsite.json
{
  "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.

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.

JSONproject.json
{ "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.

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

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.

↑ ↓ to move↵ to openSearching docsp