Every page is served at

```text
/[repo]/[version]/[...path]
```

with both prefixes optional — and the decision about whether each appears is
taken **at build time from the sources list**, never per request.

- A repository segment appears once there is more than one repository, when
  `showRepo` forces it, or — for that one source alone — when the source names a
  `slug` of its own.
- A version segment appears once a source publishes more than one ref, or when
  `showVersion` forces it.

So a single unversioned folder serves `/guides/deploying`, and nothing in the URL
betrays that repositories and versions exist at all.

## Why the prefixes are decided at build time

If both prefixes were optional per request, the first segment would be
ambiguous: `/guides/…` could be a folder, a repository or a version, and only
looking up all three would say which. Because the shape of a URL is fixed before
the first request, the router never has to guess.

What is left is a **name collision** while a prefix is active — a docs folder
called like a repository or a version. The build rejects that rather than
resolving it silently one way; see [What the build checks](/concepts/build-checks).

## The default version

One ref per repository is served without a version prefix: the first in the list,
or the one `sourceOptions.defaultRef` names. That is the URL to link to and the
one search engines are pointed at.

## Where a version sits in its life

`status` on a source or a ref is a lifecycle, not a synonym for "is the
default" — a site can publish v2 as current while v1 is merely older and v0 is
genuinely dead, and the reader has to be told which of the three they are in.

| Status       | What the reader is told                    | In the sitemap |
| :----------- | :----------------------------------------- | :------------- |
| `upcoming`   | This may still change — no upgrade advice   | Only if default |
| `current`    | Nothing                                    | Only if default |
| `maintained` | A newer version exists                     | Only if default |
| `deprecated` | A newer version exists; upgrade            | Only if default |
| `eol`        | This version is dead                       | Never          |

`upcoming` is the one that is not about age. A version can be off the default
because it has not happened yet, and telling that reader to "upgrade" is exactly
backwards. Semver cannot place a branch against a tag, so this one is stated in
the config rather than derived.

Alongside the banner, a page in a non-default version carries `noindex` and a
`canonical` pointing at the same page in the default version — otherwise a
search engine is as likely to serve v0.7.0 as today's documentation. The two
halves belong together: the banner is the visible one, the link-rel the
invisible one, and either alone leaves one audience wrong.

## When a page is missing from a version

The switcher only offers a version that actually has the page, and the canonical
link resolves to the nearest path that exists. A URL that resolves to nothing is
answered by a 404 that suggests the closest page in the navigation — versioned
URLs are easy to miss by one segment, and an empty 404 leaves the reader with
nowhere to click.