# Project layout

Where site.json, project.json, pages, assets, release notes and OpenAPI files go.

A docsp site is a folder with `site.json` and one folder per project. Every path below is relative to the folder of
the project.

```text
site.json
package.json
rocket/
  project.json
  docs/
    <version>/<locale>/<section>/<page>.md
    assets/                    images and fonts, referenced with relative paths
  changelog/
    <locale>/<release>.md
  openapi.yaml                 optional, with openapi.<locale>.yaml for translated text
```

::figure{src="../../assets/layout-light.svg" dark="../../assets/layout-dark.svg" alt="A site folder with site.json and a project folder that holds project.json, docs, changelog and openapi.yaml" caption="The folders docsp reads for one project."}

## Pages

Pages are Markdown files in `docs/<version>/<locale>/<section>/`. When the project has no `versions` block, leave the
version folder out: `docs/<locale>/<section>/<page>.md`. This site has no versions, so its pages are in
`docs/en/<section>/`.

- `<section>` must be an `id` from `nav.sections` in `project.json`. A folder that is not a section fails the build.
- The file name is the URL slug. Keep the same file names in every locale, so the language menu can switch between
  translations of one page.
- `index.md` is the page of the section itself, at `/<project>/<section>/`.
- Subfolders inside a section become part of the slug: `guides/advanced/tuning.md` is
  `/<project>/guides/advanced/tuning/`.
- A project without `nav.sections` gets one section, `guides`.

## Versions

With a `versions` block, each version listed in `versions.list` can have its own folder under `docs/`. A version
without a folder reuses the pages of the current version. See
[Versions and languages](../configuration/versions-and-languages.md).

## Assets

Put images and font files under the project folder, for example in `docs/assets/`, and reference them with paths
relative to the Markdown file. docsp serves them under `/_assets/<project>/`. Paths that start with `/` or a scheme
(`https:`) are left as they are.

## Release notes

A section of kind `changelog` reads `changelog/<locale>/*.md`, one file per release. Each file needs `version`, `date`
and `title` in its frontmatter, and may set `status`. See [Release notes](../writing/changelog.md).

## OpenAPI

A section of kind `api` gets one page per operation of the OpenAPI file named by `api.openapi`. Markdown pages in
that section (authentication, errors) come first in the sidebar. See [API reference](../features/api-reference.md).

## Section kinds

| Kind | Effect |
|---|---|
| `guides` | Markdown pages. |
| `api` | Markdown pages, plus one page per OpenAPI operation of the current version. |
| `changelog` | Release notes from `changelog/`, a list page and one page per release. |
| `sdk`, `custom` | Markdown pages, like `guides`. |

## Project ids

The project `id` is the first URL segment of the project. It cannot be a locale code of the site or a segment docsp
uses itself: `pagefind`, `404`, `_catalog`, `_assets`, `_astro`, `_docsp`, `llms.txt`, `index` and `assets`. A
project with a `symbols` block cannot have a section with id `sym`, which holds the symbol pages.
