Wednesday 7 May 2025

Ive added a secret glossary to my blog! You might find it by hovering over special links. Dont tell anyone, its a secret. At least until I can find a way to style the links without them being a distraction. Do I need to, or can they remain easter eggs?

The Idea

This project came about when I noted concern over my reliance on MDN. I always favour MDN over other sources. Im lazy. I feel guilty for not linking to the small web, the indie web, the weird web. At first I banned myself from linking to MDN. Later I mulled over the glossary idea. I think Ive solved it!

The Implementation

I write my blog posts in Markdown. For new glossary terms I now link to a placeholder rather than an external source. For example:

[React](/glossary/react.json)

This references a JSON file that has the following format:

{
  "title": "React",
  "description": "A legacy JavaScript framework (turned religion). Favoured by tech bros and famous for bloated bundles and crippling web performance.",
  "links": [
    {
      "name": "JSX.lol",
      "title": "Does anybody actually like React?",
      "url": "https://jsx.lol"
    },
    {
      "name": "React",
      "url": "https://react.dev"
    }
  ]
}

My build script replaces the markdown link with a web component:

<glossary-term id="--term-react">
  <a href="https://jsx.lol">React</a>
</glossary-term>

The first link in the JSON is used as the canonical source.

HTML wrapped in a custom element is a perfect example of progressive enhancement. For unsupported browsers there is still an accessible link inside. For browsers that support the Popover API each <glossary-term> element is enhanced with a fancy popover.

If youve missed every example so far here is the React link.

I captured a screen recording of how it should appear:

The popover is activated by either hover or keyboard focus. The escape key can also dismiss them. For touchscreens Im going to test that live&

[INSERT TEST RESULTS]

Test results: it works fine. If youve got one of those new Apple Pencils  the new new one, not the new old one  the hover effect is magical. Touch taps are taken straight to the canonical link. The popover might be open upon return. Maybe I should cancel the popover based on touch events to avoid confusion?

Failures

Initially I tried to use CSS anchor positioning.

I really tried. It left me in tears and I rage quit. It might be the most unintuitive, doesnt work like it says, infuriating web standard ever. When anchoring a popover its impossible to ensure elements stay inside the viewport (without JavaScript). Please prove me wrong!

I tried to get creative with view transitions and failed. Safari had some pixel-shifting jank going on. I tried normal transitions with allow-discrete and @starting-style and failed. In an isolated demo its all gravy but together this new CSS stuff doesnt plays nice. Its not all baseline yet so lets hope it improves. >

CSS anchors are Chrome and Chrome derivatives only right now. Safari Technical Preview claims to have support but Apple lies under oath so who knows?

Ultimately I gave up and used JavaScript to calculate position so I can support all browsers. Ill recharge morale and tackle a v2.0 at a later date.

I dont plan to immediately retrofit older blog posts with glossary links. Although that could be a quick find & replace if Im careful. Im looking for positive feedback before I do. So let me know if you like it (or not). If no one hates it Ill plough ahead, because I like it. This glossary may just be the third incarnation of my bookmarks blog.

Im tempted to use a similar technique to create popover cards for linked notes. They have more content so I need to consider that more.