Shipping Docs for Every Release: How Read the Docs Handles Version Switching

Your library just shipped 3.0, but half your users are still on 2.4. When they search for help, they land on documentation for APIs that no longer exist in their version. The fix isn't maintaining separate doc sites — it's using Read the Docs' built-in versioning, which builds and hosts a copy of your docs for every Git tag or branch you choose to publish.

The useful takeaway: versioning on Read the Docs is driven entirely by your repository's tags and branches, so the engineering decisions that matter are tag naming discipline and which versions you keep active. Get those right and readers can flip between releases from a version selector without you touching any hosting config.

What Read the Docs actually builds per version

When you connect a repository, Read the Docs watches your Git refs. Each branch or tag you activate becomes a version — an independently built snapshot of your documentation. By default you get latest (tracking your default branch) and stable (tracking your most recent tag, if you use semantic-version-style tags).

Each version is built separately and served under its own URL path segment, for example:

https://yourproject.readthedocs.io/en/latest/
https://yourproject.readthedocs.io/en/stable/
https://yourproject.readthedocs.io/en/v2.4.1/

The language code (en) and version slug are part of the path, which keeps every version independently linkable and indexable. Readers switch versions through the flyout menu (the version selector injected into the page), which swaps the version segment of the current URL rather than dropping them back at an index page.

The engineering decision: tags as the source of truth

The practical consequence of this design is that your release process is your documentation versioning process. Cutting a Git tag named v2.4.1 is what makes a v2.4.1 doc version buildable. That has two implications worth planning around:

• Tag naming must be consistent. Read the Docs parses tags to determine things like which one is "stable." A mix of v2.4.1, release-2.4, and 2.4-final produces a confusing version list and can cause the wrong tag to be treated as the stable release. Pick one scheme — semver with a v prefix is the common choice — and enforce it in your release checklist.
• Activating old versions is a deliberate choice. Every active version is a build target. If you activate fifteen historical tags, that's fifteen potential builds consuming CI time on each webhook event that triggers rebuilds. Most projects activate latest, stable, and a small set of still-supported release lines.

A worked example: adding a maintenance branch

Say you maintain the 2.4 line with backported fixes while 3.x moves ahead on main. You want docs for both. In the Read the Docs dashboard for your project (you need maintainer access to the project):

1. Open Versions. You'll see every branch and tag Read the Docs has discovered from your repository.
2. Find the 2.4.x maintenance branch (or the v2.4.1 tag) and set it to Active.
3. Trigger a build for that version and wait for it to complete.
4. Visit https://yourproject.readthedocs.io/en/2.4.x/ (the slug matches the ref name) and confirm the content reflects the 2.4 line — check a page whose content differs between 2.4 and 3.x.

Readers can now reach the 2.4 docs from the flyout selector on any page. If you want the 2.4 docs to be what people see by default, adjust the project's default version setting rather than renaming branches.

Trade-offs and limitations

• Each version is a full build. There is no cross-version incremental build shared between versions; adding a version adds its build time to your project. Large Sphinx sites with many active versions can hit build time limits.
• Old versions go stale silently. A version built from a tag never changes unless you rebuild it. If you fix a typo in the 2.4 docs, you must retag or point the version at a maintenance branch and rebuild.
• Search is per-version. The built-in search indexes each version separately, so results don't leak across versions — usually what you want, but worth knowing when debugging "missing" search hits.
• Version slugs come from ref names. A branch named release/2.4 produces an awkward URL slug. Prefer tag- and branch-names that read well in a URL.

How to verify your setup

Two quick checks after configuring versions:

1. Open a docs page, use the flyout selector to switch versions, and confirm the URL's version segment changes and the page content matches the selected release.
2. Check that deactivated versions return a 404 or are hidden from the selector, so readers don't land on unsupported releases.

Note that exact dashboard labels and URL behavior can vary between Read the Docs versions and between readthedocs.org and Read the Docs for Business; confirm against your project's admin panel if something looks different.

Closing

Version switching on Read the Docs is low-effort once you treat Git tags as the contract. Pick a strict tag naming scheme, activate only the versions you actually support, and verify the flyout and URLs after each release. Your users on older versions will stop reading docs for features they don't have — which is the entire point.