Browser extension that demonstrates the Web Annotation Discovery mechanism: subscribe to people’s annotation collections/‘feeds’, to see their notes on the web; and create & publish annotations yourself.

5.6 KiB

Web Annotation Discovery WebExtension

This browser extension implements the Web Annotation Discovery mechanism, enabling you to discover annotations and subscribe to annotation ‘feeds’ while browsing the web; then view the collected annotations on other pages you visit.

It also lets you create annotations yourself, and store/publish them on an annotation collection, so that other people view the notes you take on web pages.


Minimum viable product, or primarily a proof-of-concept: This software demonstrates a mechanism for web annotation in practice, enabling people to try it out and hopefully move forward with the idea.

The software can be used for collaborative annotation, but be prepared for possible technical glitches (including data loss or leakage), mediocre user experience, and awful interface design.

Try it out

Install the extension in a recent Firefox(-based browser). It should work in Chromium(-based browsers) too, but is not as well-tested there.

For Firefox, you can get it via Mozilla Addons. (Depending on their review process, that might occasionally be a less up-to-date version.)

On the releases page, you can download the latest version (as a .zip-file, you can rename it to .xpi or .crx if that makes you or your browser happy, but also as .zip it should work just fine). You may have to jump some hoops to install the extension directly without requiring approval by your browser vendor:

  • Firefox (temporary): Go to about:debugging, choose ‘This Firefox’, ‘Load Temporary Add-on…’, select the extension file. The extension will be removed again when you close the browser.
  • Firefox (permanently): You need a ‘developer’ or ‘nightly’ edition of Firefox, set xpinstall.signatures.required to false in about:config, and drag & drop the extension file onto the list at about:addons.
  • Chromium & co.: Enable ‘developer mode’ in about:extensions, and drag & drop the extension file onto this page. It might however be removed again when you close the browser.

If one of those options worked for you, fun can start.

Discovering & viewing annotations

Visit a compatible annotation server. For now that means running a Web Annotation Discovery Server. See its documentation for details.

Then subscribe to a collection, visit one of the pages that any of its annotations target, and the yellow notes should show up on the right side.

Creating annotations

If you have write access to an annotation collection, you can create and edit annotations in it.

Open the extension’s popup and select that collection, then click “Connect” to try it out. If you had not authenticated to the server already, your browser may prompt you for your credentials. (In Chromium-based browsers, you may have to authenticate first on the website itself, as it blocks authentication to third parties.)

Once you have connected to an annotation collection, you can create annotations by selecting text on any web page, ‘right’-clicking to get the context menu and choosing “Annotate Selection”. Write your notes and voilà, it should be stored/published on your annotation server.


Clone this repository, and install dependencies using npm install or equivalent. (Tested on Node 16 + npm 8.)

You can build it with npm run build. The extension should appear as a zip file in a folder web-ext-artifacts.

Running npm run dev should spin it up in a browser (choose which browser in vite.config.ts), with live reloading upon source file changes.

Code tour

This browser extension is written in TypeScript, transpiled by Vite (with vite-webextension-plugin), using Preact for the UI. It uses, and is co-developed with, Apache Annotator.

The extension’s local storage (abstracted by Dexie) keeps a list of known annotations and of the annotation sources they come from. Each source that is an Annotation Container is considered a ‘feed’, and its annotations are downloaded again every couple of minutes (yes that could be made more efficient).

For authentication to an annotation source (presumably required for creating annotations), this extension depends on the web browser’s capabilities; for simplicity (and because this would ideally be the browser’s job anyway), this extension has no clue about accounts, passwords, etc. This has been tested with HTTP Basic Auth, but possibly a server requiring e.g. client-side TLS certificates would work too. When the user “connects” to an annotation collection they want to store annotations in, the extension simply tests whether it can create a bogus annotation (which it directly deletes again).


This is free and unencumbered software released into the public domain. Except the icons in src/assets/icons/, which are MIT-licensed by the Bootstrap Authors.


This project was funded through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission’s Next Generation Internet programme.