web-annotation-discovery-webextension

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.

Status

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.

Note that you may need to jump some hoops to install an extension that has not been approved by the browser vendor itself. (An approved version may be available soon.)

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

If one of those 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.

Develop

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).

Licence

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.

Acknowledgements

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.