Highlight selected list item when clicking on links

[lgfa29]

Most RFDs use a reference to an item in the "External References" list in links. This requires users to remember the item they clicked, and sometimes the link text itself may differ from the item list.

It would be helpful to highlight the item that was clicked so that users can quickly find the address they intend to navigate to. This could, in theory, be done with just a little CSS:

.bibliography li:has(:target) {
  background-color: rgb(from var(--theme-accent-700) r g b / 40%);
}

But due to remix-run/remix#6432, some JavaScript may be required to achieve a similar effect.

[benjaminleonard]

We are already intecepting the link with https://github.com/oxidecomputer/design-system/blob/028e05f0692de8d904d2e1b151ec8e6cf21da766/components/src/asciidoc/use-delegated-links.ts#L33 which we might be able to do something with — like a callback that we pass whenever the user clicks a link and add something to state to do this.

But I'm thinking if we can grab the external reference, pull out the URL and navigate there directly instead. Would that be preferable? Falling back to the external reference if that doesn't product a valid URL?

Unfortunately whilst we have a custom renderer for AsciiDoc – the tree itself does not go down to the inline block level. Which makes sub-block interactions a little more awkward.

[lgfa29]

Hum...good question. Personally, and from the RFD links I clicked so far, that seems like it would be a good flow, but there may be cases where a link to the references was the intended behaviour, so it may better to check with others.

I would say that, at least for now, highlighting the list item would be a big improvement, and seems like a simple and reliable implementation (famous last words, I know 😅).

Longer term, I think the way Wikipedia handles links, references, and footnotes is useful.

Links are just links, and the navigate you to another page.

References are numbered superscripts that scrolls you down to the list of references, with the one you clicked highlighted (I forgot to mention in my initial comment, but that's where I got this idea in the first place). They also include a ^ icon to send you back to the text, which I also find useful. If a reference is used in many places, the arrow has multiple links next to it, like ^ a b.

Screen.Recording.2025-10-10.at.10.05.56.AM.mov

Footnotes are similar to references, but they use letters instead of numbers.

But I'm also not sure how this would work in Asciidoc, or how much work it would require.