How to Do Literate Programming for the Web
BraindumpShow the element itself
The general guide says a diagram beats a paragraph wherever the content is visual. On the web the bar is higher still: the content is not merely visual, it is the live artifact itself, and the export can hold it. So whenever the prose introduces something the reader will see or touch — a styled element, a widget, a page fragment — show that thing, rendered, right there.
Embed the real element, produced by the very block that tangles, so it re-renders whenever the document is rebuilt and stays in lockstep with the code. The reader sees what the code yields the moment the document presents it.
CSS renders to a picture, so show the picture
A CSS rule is a description of an appearance — and an appearance is exactly the kind of thing prose translates badly and the reader pictures wrongly. Never let a CSS block stand on its words alone. Beside every rule, place in the HTML export a rendered sample it applies to: the box with its border and shadow, the button in each of its states, the grid with its tracks drawn. The reader reads the rule and sees, in the same glance, what it produces.
When the rule has variants — hover, focus, disabled, the breakpoints of a responsive layout — show each. A difference the reader can see beats a difference the prose merely asserts, and the gap between “what I think this declares” and “what it actually paints” closes on the spot.
Frame a live component beside the prose that builds it
For a web app, each element the prose presents is worth seeing out of its
surrounding context, so the reader takes in what it looks like and how it
behaves on its own. Embed it — an iframe pointing at an isolated render of
just that element, or any equivalent live embed — next to the block that
builds it.
Out of context is the point. Stripped of the rest of the page, the element shows its own appearance and its own interactions, with nothing around it to explain away a glitch or borrow credit for a behavior. The reader can poke at the real thing directly; seeing and clicking it answers in a second what a paragraph about it never quite settles.
Animate the interaction
Some of what the prose claims is a behavior over time — a transition, a drag, a focus moving, a value updating as a pointer sweeps across the widget. Only motion conveys it.
Where it is feasible, embed a small looping demonstration: a short JS animation, a scripted cursor that performs the gesture and repeats, a clip of the interaction playing on a loop. The reader watches the very thing the sentence describes happen, again and again, instead of assembling it in their head from a description. A loop of the real behavior is the strongest evidence the document can offer that the words are true — and it costs the reader nothing but a glance.