Read the Docs redirect precedence when multiple rules match one path

Question

Read the Docs supports project-level redirects configured in the dashboard, including exact-path and wildcard entries that map old documentation URLs to new versions or external targets. A documented gap is the evaluation order when several redirect rules could match the same incoming request path.

The uncertainty is whether rules are processed sequentially in dashboard order, ranked by pattern specificity, or resolved by an internal priority. Overlapping wildcard and exact rules can produce different destinations depending on which precedence model applies. The same logical path may also be reachable under versioned URL prefixes or custom domains, adding another layer of ambiguity.

Behavior may differ between the hosted service and self-hosted instances, and precedence is not guaranteed to remain stable across platform updates. The platform documentation does not define the ordering contract, and the dashboard does not expose an explicit priority field.

Which precedence model does Read the Docs apply when multiple redirect entries match the same path?
How do versioned URL prefixes and custom domains affect that ordering?
What observable signal should operators use to confirm the active rule?

Tasadduq Burney · Answer

Precedence ModelRead the Docs evaluates matching rules in the order they appear in the project’s redirect list; the first rule that matches wins. No documented specificity ranking prefers exact paths over wildcards, so the list order determines which rule is applied.Effect of Versioned Prefixes and Custom DomainsHost and version resolution occur before matching. The platform normalizes the path after determining the project (via domain or subdomain) and the version (via URL prefix). The resulting path is then matched against the project‑level redirect table, so a rule defined for the project applies regardless of the host or version used.Confirming the Active RuleUse an HTTP HEAD request to see which rule fired. Example:curl -I https://your-project.readthedocs.io/en/old-path/The Location header and status code reveal the destination; compare this with the order of rules shown in the dashboard redirects list to infer which rule was evaluated first.

Read the Docs redirect precedence when multiple rules match one path

1 answer

Precedence Model

Effect of Versioned Prefixes and Custom Domains

Confirming the Active Rule

Your perspective belongs here.

0 question comments