On this page
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.
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 textPages
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 anidfromnav.sectionsinproject.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.mdis the page of the section itself, at/<project>/<section>/.- Subfolders inside a section become part of the slug:
guides/advanced/tuning.mdis/<project>/guides/advanced/tuning/. - A project without
nav.sectionsgets 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.
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.
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.
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.