I have a bad habit of assuming my audience is entirely technical.
Either that or I remember that one non-technical reader that emailed me asking to explain a concept (this is for you) and over-explain - completely disrupting both reading and writing flow.
Most writing assumes its audience. That assumption has a cost: the curious reader will hit a term they don't know and click off the page to search or paste a sentence into AI or open a new tab and never come back - I'm guilty of all three.
Reading is an immersion and it should be frictionless. Every interruption breaks the thread.
I've been thinking about a solution that helps with both reading and writing while being intuitive and visually beautiful. I explored a few options:
- Footnotes: nobody clicks them and will send you to the marina trench and have you scrolling back up to surface for air
- Parentheticals (something I default to a lot < lol): they interrupt the sentence they're trying to explain
- Separate "beginner" posts: condescending, doubled maintenance burden and readers don't know which one to read
- Tooltips: hover doesn't exist on mobile also kinda ugly and fiddly
- Page annotations: a good option that I'm still considering
Giving the reader control
Then I realised, why am I deciding for you? Wouldn't it be great to have a way to let a reader choose their depth?
A technical reader will skip past expanded context they don't need. A non-technical reader will click on the words they don't recognise. Both read the same post seamlessly.
I call this concept "reading at your own depth". I like to think of it as respecting the reader enough to give them control.
This also gives the writer more control. Write the post you actually want to write, then go back and annotate the terms that might lose someone. Your flow, prose, ideas stay intact while appealing to a broader audience.
Peek
Peek is a small client component — ~120 lines using useState, useEffect, and React Context.
Click a coloured word and inline context streams in at reading speed.
Nest them — each level gets its own color.
Children can be anything — not just text. Here's a bar chart living inside a Peek.
Or an image — click next token prediction to see an image inline.
The stream animation is intentional — it feels like the text is being revealed rather than dumped, closer to how you'd explain something verbally than how a tooltip feels.
Also lowkey people are getting AI-brained and can't consume content that is not streamed! Big block of words intimidating!
Usage
Install directly:
Or clone from Github and copy-paste the single file — works with any .mdx, .tsx, or .jsx setup with no configuration required.
Basic — a single term with a definition:
The model uses <Peek trigger="RLHF">Reinforcement Learning from Human Feedback —
someone paid $3/hr to vote yes or no on a response</Peek> to steer outputs.Nested — the definition itself contains an expandable term:
We use <Peek trigger="agents">autonomous programs that plan and execute tasks using
an <Peek trigger="LLM">Large Language Model — the neural network that predicts the
next token given everything it has seen so far</Peek> as their reasoning engine</Peek>.Rich trigger — the clickable word can be formatted, not just plain text:
<Peek trigger={<code>temperature</code>}>a sampling parameter between 0 and 2 —
higher values make outputs more random, lower values more deterministic</Peek>Is this new?
I'm not sure. It seems intuitive enough that something like it must exist but maybe not in this context?
I'm guessing it's not a major focus as most writing lives in plain Markdown files or <p> tags which don't support JSX. Peek requires JSX, which narrows the audience to MDX blogs, React docs and component-driven content.
Isn't this just a glorified glossary?? Not really, a glossary defines terms. Peek lets you go on tangents, add asides, inject context, tell a joke that needs setup without breaking the sentence you're in.
Did this need to be an npm package? Initially it was simple so no, then I started thinking about customisability and reusability as one does with any component and it seemed like it was necessary. Also vanity of seeing a project I created have a weekly download chart and a page on npm.js.
This idea came as a tangent when speaking to Claude about tangents. To learn more about what I mean by tangent, subscribe for the upcoming post.
Questions or thoughts? Reach out to me here -> ossamachaib.cs@gmail.com.