# 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. [Web Annotation Discovery]: https://code.treora.com/gerben/web-annotation-discovery ## 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. 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. [via Mozilla Addons]: https://addons.mozilla.org/firefox/addon/web-annotation-discovery/ [releases]: https://code.treora.com/gerben/web-annotation-discovery-webextension/releases ### 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. [Web Annotation Discovery Server]: https://code.treora.com/gerben/web-annotation-discovery-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). [TypeScript]: https://typescriptlang.org/ [Vite]: https://vitejs.dev/ [vite-webextension-plugin]: https://github.com/aklinker1/vite-plugin-web-extension/ [Preact]: https://preactjs.com/ [Dexie]: https://dexie.org/ [Apache Annotator]: https://annotator.apache.org/ ## 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](https://nlnet.nl/project/WebAnnotation/) through the NGI0 Discovery Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme.