One Repo, Many Docs: How Read the Docs Turns Git Tags Into Versioned Documentation

Your library ships v2.0 with breaking changes, and within a day the support questions start: "The docs say to call connect(), but that function doesn't exist." The docs are fine — for v2.0. The user is still on v1.4. What you actually need is documentation that exists in parallel: one set per release, all built from the same repository, with readers able to flip between them. Read the Docs does this out of the box, and the mechanism is simpler than most people assume: it builds one documentation site per Git branch or tag.

The core idea: versions are just Git refs

When you connect a repository to Read the Docs, it scans your branches and tags and treats each enabled one as an independent documentation version. Each version gets its own URL namespace:

• https://yourproject.readthedocs.io/en/latest/ — built from your default branch (usually main)
• https://yourproject.readthedocs.io/en/stable/ — aliased to your most recent non-pre-release tag
• https://yourproject.readthedocs.io/en/v1.4.0/ — built from the tag v1.4.0

The stable/latest split gives readers clear semantics: stable documents what they'd install from a package manager today, while latest documents what's coming. A version selector in the sidebar (the flyout menu, typically lower-left) lets readers jump between them. There's no extra publishing step — pushing a tag and triggering a build is the whole workflow.

A worked example: publishing a v1.4.0 doc set

Assume your project already builds on Read the Docs from main, using Sphinx with a .readthedocs.yaml config at the repo root. To publish docs for a release, run these locally with write access to the repository:

git checkout -b release-1.4
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0

Then, in the Read the Docs project admin (you need maintainer access on the project), open Versions and make sure v1.4.0 is set to Active. New tags are often activated automatically depending on project settings, but it's worth checking — a tag that exists in Git but is inactive in the dashboard won't build.

Once the build finishes, verify two things:

1. Visit https://<your-project>.readthedocs.io/en/v1.4.0/ directly. It should load the docs as they existed at that tag.
2. Open the version selector on any page. You should see latest, stable, and v1.4.0 listed, and each entry should load a distinct build.

If stable still points at an older release, check that your tag name parses as a non-pre-release version — tags like v1.4.0-rc1 are intentionally excluded from the stable alias.

Isolation is the underrated feature

Each version builds independently, with its own copy of your .readthedocs.yaml and its own dependencies as pinned at that ref. This means you can experiment safely: bump Sphinx to a new major version, swap themes, or add an extension on main, and the v1.4.0 docs keep building with the exact configuration they shipped with. For long-lived maintenance branches this matters a lot — you can backport a doc fix to release-1.4 without dragging along two years of tooling churn.

Trade-offs and sharp edges

A few limitations are worth planning around:

• Build cost scales with versions. Every active version consumes build time and storage on every trigger. Projects with dozens of tags should deactivate old versions in the dashboard rather than leaving everything on. Deactivating keeps the built docs' configuration tidy; deleting removes them entirely.
• Version names must be URL-safe. Tags with slashes or unusual characters can produce versions that build fine but behave oddly in the selector. Stick to simple names like v1.4.0 or 1.4.
• Renames break links. Redirects between versions are not automatic. If you rename a tag or retire a version, external links 404 unless you configure redirects manually in the project admin. Treat published version URLs as permanent.
• Deleting a tag removes the version. The tie between Git refs and Read the Docs versions is literal — delete the tag and the version disappears from the selector. That's useful for cleanup but surprising if you do it accidentally.

Where to start

If your project already builds on Read the Docs, the cheapest experiment is: push one annotated tag, activate it in the Versions dashboard, and confirm the versioned URL and selector entry appear. That ten-minute exercise tells you whether your config is version-ready. From there, decide your policy — which releases get docs, when old ones get deactivated — and write it down in your contributing guide, because the tooling will happily build whatever you tell it to.