Principle:Dagster io Dagster Documentation URL Redirect Management
| Knowledge Sources | |
|---|---|
| Domains | Documentation, URL_Management, Deployment |
| Last Updated | 2026-02-10 12:30 GMT |
Overview
Design principle for maintaining backward-compatible URLs when documentation structure changes, using declarative redirect rules at the edge network level.
Description
Documentation URL Redirect Management is the practice of maintaining a mapping from old documentation URLs to their new locations whenever the site structure is reorganized. This prevents broken links from search engines, bookmarks, external references, and previously published content. The principle uses HTTP 308 (Permanent Redirect) responses served at the edge network (CDN) level, ensuring zero-latency resolution without hitting the application server. Wildcard patterns (e.g., /old-section/:path* to /new-section/:path*) allow entire directory trees to be redirected with a single rule.
Usage
Apply this principle whenever documentation pages are moved, renamed, or restructured. It is critical during major site reorganizations (e.g., renaming "dagster-cloud" to "dagster-plus") where hundreds of URLs change simultaneously. Every URL change should be accompanied by a redirect rule to maintain link integrity.
Theoretical Basis
The core mechanism is declarative URL rewriting at the edge:
- Source pattern matching: Each redirect rule defines a source URL pattern with optional wildcards
- Destination mapping: The target URL can reference captured path segments from the source
- Permanence classification: Permanent (308) redirects instruct search engines to update indexes; temporary (307) redirects preserve the original URL in indexes
- Priority ordering: More specific rules are evaluated before wildcard catch-all rules
Pseudo-code Logic:
# Abstract redirect resolution algorithm
def resolve_request(url, redirect_rules):
for rule in redirect_rules: # Ordered by specificity
if match(url, rule.source):
target = interpolate(rule.destination, captured_segments)
status = 308 if rule.permanent else 307
return redirect(target, status)
return serve_page(url) # No redirect matched