mdn / mdn/rari

Resolve xref templates via static page index instead of guessing URLs

Open
#683 0 comments 0 reactions 1 assignee View on GitHub

@caugner is already working on this.

Since May 15, 2026.

p1
Dominant language
Rust
Stars
57
Forks
47
Avg merge
1d 11h
Merged PRs (30d)
68

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.