When Does Read the Docs Serve Stale HTML After a Successful Build?

Direct answer

The stale HTML is governed by the CDN edge cache's Time-to-Live (TTL) and invalidation behavior for the mutable alias URL—not by the build itself. Read the Docs repoints /latest/ to the new build ID when a build succeeds, but the CDN may continue serving a previously cached copy of that alias path until the cache entry expires or an invalidation reaches the edge.

Confirmed behavior vs. likely explanation

Confirmed: /latest/ and /stable/ are mutable pointers to the most recent successful build. Versioned URLs such as /en/1.2/ map to a specific build artifact and are effectively immutable. Read the Docs does not expose a user-controlled purge for the CDN layer.

Likely explanation: Because the alias is a single URL whose target changes, the CDN treats it as one cache key. When the target changes, each edge must either wait for TTL expiration or receive an invalidation signal. Propagation delays can cause regional inconsistencies where different networks see different content at the same time. Browser-side caching can extend the perceived staleness beyond the CDN's TTL. Exact TTL values and invalidation timing are not publicly documented by Read the Docs and may change; treat the mechanism as CDN-dependent. This analysis assumes standard Read the Docs hosting; self-hosted or reverse-proxy setups may differ.

Verifying the difference

To confirm whether the alias is lagging while the versioned URL is fresh, compare response metadata and content across networks:

• Inspect cache headers for both URLs. Exact header names depend on the CDN provider, but Age or X-Cache style headers often reveal whether a response was served from cache and how old it is.
• Check the build timestamp in the rendered page footer. If the footer shows an older build ID than the latest successful build, the HTML is stale regardless of headers.
• Request both URLs from multiple networks or regions. If /latest/ differs across regions while /en/<version>/ is identical, the discrepancy is edge-cache propagation.

curl -sSI "https://example.readthedocs.io/en/latest/" | grep -iE 'age|x-cache|cache-control'
curl -sSI "https://example.readthedocs.io/en/1.2/" | grep -iE 'age|x-cache|cache-control'

One diagnostic that changes the advice

Are you seeing stale content only under /latest/ and /stable/, or do versioned URLs also serve older builds? If only the aliases lag, the issue is alias-cache TTL and propagation. If versioned URLs also lag, the problem is likely upstream of the CDN or local browser caching, and the alias explanation does not apply.