Serving Multiple Product Versions with ReadTheDocs Git Tags – A Practical Guide

Problem and Takeaway

When a software product releases several major versions, users often land on the same documentation page and struggle to find the right instructions. The useful takeaway is that ReadTheDocs can automatically build and host separate documentation for each version by using Git tags.

Why Versioned Documentation Matters

Versioned documentation lets each product release show instructions that match its own API and UI. Readers can switch versions from a sidebar, and search indexes each version independently, reducing support tickets.

Configuring ReadTheDocs with Git Tags

ReadTheDocs reads the source from a repository and follows the readthedocs.yml file to decide which ref (branch or tag) to build. The key setting is gitref:.

1. Open readthedocs.yml in your repository (you need write permission on the repo).
2. Add or edit the version: section to point at a tag, e.g.:

   version:
     latest:
       repo: yourorg/yourproject
       branch: main
     v2.0:
       repo: yourorg/yourproject
       tag: v2.0.0

After committing the file, push the tag:

git tag v2.0.0
 git push origin v2.0.0

ReadTheDocs detects the new tag on the next build and creates a build for the v2.0 version.

Verifying the Build

To confirm the version mapping worked, perform two checks:

• Inspect the generated URL: https://readthedocs.org/projects/yourproject/v2.0/. The /v2.0/ segment must appear, indicating the tag was recognized.
• Review the build log for the v2.0 version. Look for a line like Building version v2.0 from tag v2.0.0. Missing logs suggest the gitref setting is incorrect.

Risks include a typo in the tag name or an omitted gitref entry, which can cause the build to fail or produce a missing version.

Trade‑offs and Limitations

The free tier of ReadTheDocs limits storage space and build minutes. Large documentation sets or frequent tag updates may exceed these limits, resulting in delayed builds or build failures. Additionally, the configuration can be unintuitive; a misplaced colon or missing indentation will prevent the correct version from being built.

Actionable Closing

To start, add a gitref: entry for each major release tag in readthedocs.yml, push the tags, and verify the versioned URLs. Monitor build minutes on the dashboard, and if you approach the free tier limits, consider upgrading or pruning old tags. This approach gives your audience clear, version‑specific documentation without extra manual steps.