# URL scheme

How docsp builds page URLs from locale, project, version, section and file name.

Every page URL has the form:

```text
/<locale>/<project>/<version>/<section>/<page>/
```

The default locale of the site and the current version of the project are left out. The canonical URL of a page in
the default locale and the current version is therefore `/<project>/<section>/<page>/`.

| File | URL |
|---|---|
| `rocket/docs/2.0/en/guides/quickstart.md`, `en` is the default locale, `2.0` the current version | `/rocket/guides/quickstart/` |
| `rocket/docs/1.x/en/guides/quickstart.md` | `/rocket/1.x/guides/quickstart/` |
| `rocket/docs/2.0/de/guides/quickstart.md` | `/de/rocket/guides/quickstart/` |
| `rocket/docs/2.0/en/guides/index.md` | `/rocket/guides/` |
| `rocket/changelog/en/2.0.0.md` with `version: 2.0.0`, in the section `changelog` | `/rocket/changelog/2.0.0/` (the slug is the `version` field) |
| An OpenAPI operation `createLaunch` in the section `api` | `/rocket/api/create-launch/` |

## Other URLs

| URL | Content |
|---|---|
| `/` | The portal: one card per project. `/<locale>/` for other locales. |
| `/<project>/` and `/<project>/<section>/` | Redirect pages to the first page of the project or section. |
| `<page URL without the trailing slash>.md` | The page as Markdown, for example `/rocket/guides/quickstart.md`. |
| `/<project>/llms.txt` | List of the pages of the current version. |
| `/<project>/sym/` | Symbol index, when the project has a `symbols` block. |
| `/_assets/<project>/...` | Images and fonts of a project. |
| `/pagefind/` | The search index. |
| `/404.html` | The not found page. |
| `/_catalog/` | Component catalog, only in `docsp dev` and in `docsp build --catalog`. |

OpenAPI operation slugs are the `operationId` in kebab case, or the method and path when there is no `operationId`.

## Redirects

Redirect pages are static HTML with a meta refresh. Besides the project and section redirects, you can list your own
in `site.json`:

```json title="site.json"
{
  "redirects": [{ "from": "/rocket/guides/start/", "to": "/rocket/guides/quickstart/" }]
}
```

`status` is accepted but has no effect on static output.

## Links between pages

Write links to other pages as relative links to their Markdown files. docsp turns them into page URLs in the same
locale and version:

```md
See [the quickstart](./quickstart.md) and [errors](../api/errors.md#rate-limits).
```

:::warning[Root of the domain only.]
docsp writes absolute URLs that start at `/`. Serving the site under a path such as `example.org/docs/` is not
supported.
:::
