Skip to content

Resolve xref templates via static page index instead of guessing URLs #683

Description

@caugner

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:

  1. Every guessed-then-redirected link raises a templ-redirected-link flaw, drowning out genuine issues in the flaw output.
  2. 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:

  1. Resolution becomes page → accepted inputs, rather than input → guessed URL, which matches how the content is actually organized.
  2. It opens the door to making xref invocations auto-fixable, since the index gives us the canonical target for any accepted input.

Metadata

Metadata

Assignees

Labels

p1We will address this soon and will provide capacity from our team for it in the next few releases.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions