Version-aware documentation on ReadTheDocs without breaking search

The outdated docs problem

You publish v2 of your library, push the tag, and ReadTheDocs builds /en/v2/. A week later, a user searches for "authentication," lands on /en/v1/, and follows instructions that no longer apply. Worse, a "new in v2" callout appears on v1 because the build never knew which version it was serving.

ReadTheDocs builds documentation from Git tags and branches, serving each version under its own URL path, such as /en/v1.0/ and /en/v2.0/. The platform sets the READTHEDOCS_VERSION environment variable during every build, but you still have to tell your content and configuration how to use it.

Pin versions in readthedocs.yml

A readthedocs.yml file at the repository root tells ReadTheDocs which build environment and Sphinx configuration to use. Without it, ReadTheDocs falls back to defaults that may not match your local setup.

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
sphinx:
  configuration: docs/source/conf.py

This configuration is committed to the repository, so every build uses the same Python version and Sphinx entry point. The build.os value matters because ReadTheDocs runs in a containerized image; if your local machine uses Python 3.13 but the build uses 3.11, an extension that works locally can fail silently on ReadTheDocs.

Make content aware of its version

ReadTheDocs injects READTHEDOCS_VERSION during every build. Its value is the Git tag or branch name, such as v2.1.0 or stable. You can read it in Sphinx's conf.py and use the ifconfig directive from the sphinx.ext.ifconfig extension to show or hide blocks.

# docs/source/conf.py
import os

extensions = ["sphinx.ext.ifconfig"]

rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest")

.. ifconfig:: rtd_version == "v2.1.0"

   This API endpoint is available starting in v2.1.0.

Locally, READTHEDOCS_VERSION is usually unset, so the block falls back to latest. That mismatch is a common source of "it works locally" surprises: the conditional block appears on ReadTheDocs but not in your local preview, or vice versa.

Worked example: tag a release and confirm the version

1. Open a terminal in your repository clone. You need write access to push tags.
2. Create and push a version tag:

git tag v2.1.0
git push origin v2.1.0

1. In ReadTheDocs, open the project's build settings and confirm the webhook is active for your Git provider.
2. Watch the build log for the new tag. Look for a line similar to:

READTHEDOCS_VERSION=v2.1.0

1. Visit https://<project-slug>.readthedocs.io/en/v2.1.0/ and confirm the conditional block appears only there, not under /en/stable/. Replace <project-slug> with your ReadTheDocs project identifier, the short name in your project URL.

If the build fails, check the log for missing Sphinx extensions. ReadTheDocs' container image may not include obscure extensions that work on your laptop, and the failure can appear as a missing page rather than an obvious error.

Search stays version-scoped by default

A search on /en/v2.1.0/ does not return results from /en/v1.0/. That isolation prevents users from finding obsolete instructions, but it also means each version carries its own search index. With many versions, indexing time and storage grow, and relevance can degrade. ReadTheDocs supports reindexing through its API, and you can tune indexing behavior if search slows down.

Trade-off: convenience versus surprise

Versioned documentation is useful, but every tag multiplies build time and search index size. A team that tags every pull request will quickly accumulate stale versions. A practical rule is to keep only major releases and the default branch active, and to retire old versions from the ReadTheDocs admin UI rather than leaving them indexed forever.

Check before you announce

• Push at least two tags and verify that /en/v1.0/ and /en/v2.0/ show different content.
• Confirm READTHEDOCS_VERSION appears in the build log and matches the tag.
• Run a search on each version and confirm results stay within that version.

If those checks pass, your documentation versions are isolated and version-aware. If they fail, inspect the build log before changing readthedocs.yml; most failures are environment mismatches, not configuration syntax errors.