Introducing Annotations

I added a new feature to this site: inline annotations with hover tooltips, similar to what Wikipedia uses for footnotes and extra context.

What Are Annotations?

Annotations let me add extra context, links, or explanations to specific words or phrases without breaking the flow of the text. The annotated term gets a small blue superscript plus sign like this one[+], and when you hover over it (or tap on mobile), a tooltip appears with the annotation content.

How They Work

Annotations follow a reference/definition pattern inspired by Markdown footnotes. You mark a term inline with +[key] or +[key](label) and define the annotation body at the bottom of the file:

The +[RISC-V](RISC-V) is an open standard ISA.

Then at the bottom of the file:

+[RISC-V] RISC-V is an open **standard** instruction set
architecture based on established RISC principles.

This renders the term RISC-V⁺ inline and places the tooltip content (parsed as full Markdown) after the document.

The annotation content supports full Markdown formatting:

• Bold with **bold**
• Italic with *italic*
• Code with backticks
• Links with standard Markdown link syntax
• Block-level content: paragraphs, lists, blockquotes, code blocks

Why Annotations?

Long-form technical writing often needs to balance readability with thoroughness. Annotations let me:

1. Define terms in place — no need to break the paragraph with a definition
2. Provide optional deep dives — readers who want more context can hover; others can keep reading
3. Cite references — link to source material without cluttering the prose
4. Add asides — a quick tangent or clarification without footnoting

Example

Here's a paragraph using annotations to add extra context:

The JetBrains Mono⁺ typeface has become increasingly popular among developers, thanks to its ligatures⁺ and clean design. Unlike traditional monospace fonts that were designed for typewriters, JetBrains Mono was crafted specifically for reading code on screens, with differentiated characters⁺ that reduce visual ambiguity.

And here's a reference-style annotation showing the tooltip with a link:

The lume⁺ static site generator powers this entire website.

Technical Notes

• Zero dependencies — the entire feature is pure Markdown-it plugin + vanilla JS
• Split syntax — +[key](label) marks the term inline; +[key] … defines the content
• Plus indicator — a ⁺ superscript marks each annotated term
• Markdown in tooltips — the annotation body supports bold, italic, code, and links using standard Markdown syntax
• Block-level content — lists, blockquotes, and code blocks inside annotations
• Build-time errors — missing definitions and unused definitions both fail the build with clear messages
• Graceful degradation — if JavaScript is disabled, the note text falls back to the aria-label attribute
• Mobile-friendly — tap the ⁺ superscript to show/hide the tooltip
• CSS-only hover — on desktop, the tooltip appears on hover without requiring JS (JS enhances it for positioning and click-to-toggle)

How to Add Annotations

To use annotations in future posts, mark the term inline and define it at the bottom:

The +[term] is important.

+[term] Your explanation with **Markdown** here.

For block-level annotations:

+[example](Example)
    with indented block for extra content, including:
    - block level markdown
    - lists
    - etc.

Note that:

• Every +[key] must have a corresponding +[key] … definition (build-time error otherwise)
• Every definition must be referenced at least once
• Keys are internal identifiers and never appear in the output
• Use +[key](display label) to show a different term than the key

That's it! The CSS and JS are already included in the site layout — no extra setup needed.