URLs and versions

Every page is served at

/[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.

#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.

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.