# 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](./reference.md) 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.

```json title="site.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](../guides/project-layout.md#section-kinds).

```json title="project.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

```json title="site.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.

### 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.

```json title="project.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.

### 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](./theming.md).
- Code block colors: [Code themes](./code-themes.md).
- Versions and translations: [Versions and languages](./versions-and-languages.md).
- API pages from OpenAPI: [API reference](../features/api-reference.md).
- Links from code to symbols: [Symbol index](../features/symbols.md).
- Search filters: [Search](../features/search.md).
- Markdown twins and `llms.txt`: [LLM outputs](../features/llm.md).

## 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.
