Our cross-reference templates (cssxref, jsxref, domxref, htmlelement, etc.) were written assuming a flat URL structure, deriving the target URL by appending the argument to a fixed base path — e.g. {{cssxref("display")}} → Web/CSS/display.
That assumption no longer holds after recent content reorganizations, which introduce nested paths like Web/CSS/Reference/Properties/display.
Existing invocations mostly still render correctly because Rari follows redirects during resolution, but this has two downsides:
- Every guessed-then-redirected link raises a
templ-redirected-link flaw, drowning out genuine issues in the flaw output.
- Pages that exist only under the new structure (with no redirect from the old path) can't be referenced at all, since there's nothing for the guess to redirect through.
Instead, we should build an index mapping each xref-able page to the set of argument values that should resolve to it, and have the templates look up the index rather than constructing a URL.
Benefits:
- Resolution becomes page → accepted inputs, rather than input → guessed URL, which matches how the content is actually organized.
- It opens the door to making xref invocations auto-fixable, since the index gives us the canonical target for any accepted input.
Our cross-reference templates (
cssxref,jsxref,domxref,htmlelement, etc.) were written assuming a flat URL structure, deriving the target URL by appending the argument to a fixed base path — e.g.{{cssxref("display")}}→Web/CSS/display.That assumption no longer holds after recent content reorganizations, which introduce nested paths like
Web/CSS/Reference/Properties/display.Existing invocations mostly still render correctly because Rari follows redirects during resolution, but this has two downsides:
templ-redirected-linkflaw, drowning out genuine issues in the flaw output.Instead, we should build an index mapping each xref-able page to the set of argument values that should resolve to it, and have the templates look up the index rather than constructing a URL.
Benefits: