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

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
A site folder with site.json and a project folder that holds project.json, docs, changelog and openapi.yamlA site folder with site.json and a project folder that holds project.json, docs, changelog and openapi.yaml
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.

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.

↑ ↓ to move↵ to openSearching docsp