Do-it-yourself anchoring and the evolution of the Hypothesis toolkit

Here’s a picture of a web page with two annotations made using Hypothesis. If you’re familiar with our tool, you’ll notice that these highlights are unusual. Normally they’re yellow, here they’re gray and green. Another difference: hovering over an annotation’s highlight displays its text in a tooltip.

Opening the Hypothesis sidebar reveals the source of the color-coded highlights: tags with the names of the colors.

These features — tag-controlled highlight colors, tooltips — are not built into the Hypothesis application. I’ve added them to the page using a simple script. I won’t focus on the details here, because if you’re not a programmer your eyes will glaze over. But I want everyone to appreciate a key point: the script is simple, and that’s because it leverages some of Hypothesis’ core technology to do the heavy lifting.

When you annotate a web page using Hypothesis, your annotations are stored in the cloud. A visitor to the page sees those annotations through the lens of the Hypothesis software which can take the form of a Chrome extension, a web proxy (, a script embedded in the page, or a bookmarklet. In all these incarnations the application queries a remote database for annotations that belong to the page, and anchors them to the page.

That anchoring capability was, until recently, deeply wired into the application. Now it’s available as a set of open source libraries that can be used independently of the application, to replace or augment the built-in viewer.

In the vast majority of cases that won’t be necessary. We aim to make Hypothesis as generally useful a product as we can. But there will always be special needs. Some require the ability to query, read, write annotations programmatically, and for those purposes there’s an API. Others will require tweaking the way in which annotations are anchored and displayed. Now there’s a way to do that too. Hypothesis has always been both a product and a toolkit. With the extraction of anchoring technology into resusable modules, the toolkit becomes more capable.