This blog is now powered by neat-annotations — a zero-JS CSS library for hand-drawn arrows, handwritten labels, and inline highlights.

Here is a quick reference guide on how to annotate text in your Markdown articles!

Inline Highlights (Recommended for body text)

When annotating inline body text, use highlight-only markers without floating notes or arrows. They render cleanly without disrupting line height or overlapping adjacent text:

You can mark important words, highlight key metrics, or emphasize critical commands seamlessly inside any paragraph.

Code & Specification Showcase (“In the Wild”)

When you want to point arrows at code tokens, parameters, or specifications, give lines generous line-height (3.4em) so hand-drawn labels sit cleanly around the target text:

●●● docs/specs/cli.md

- [ ] CLI-042 Add export command #cli !high @blocked_by:CLI-041

Write task output as JSON for scripts and agents

Markdown Markup Syntax

To add annotations to your Markdown posts, simply wrap your target text in a <span> tag:

<!-- Highlight only (no arrow) -->
<span class="ann ann-amber">important note</span>

<!-- Arrow pointing South with handwritten label -->
<span class="ann ann-s ann-blue" data-note="stable ID">CLI-042</span>

<!-- Arrow pointing North with handwritten label -->
<span class="ann ann-n ann-amber" data-note="description">JSON</span>