Hypothesis web annotation in Firefox: cellphone and PC

Update June 8th, 2020: As of today, an unofficial extension is available for Firefox desktop!

Hypothesis is a great web annotation tool that lets you annotate any webpage, and share your annotations publicly, within private groups, or keep them for your own.

Although webpage owners can add the necessary code to enable annotations for anyone visiting their webpages, you can annotate any webpage by simply injecting the necessary code: the Hypothesis client. To do so, the easiest way is to use a browser extension, which is currently only available for Google Chrome.

If you use other browser (e.g. Firefox, Safari) or use Chrome in your cellphone (which doesn’t accept extensions), you can still use the bookmarklet, something like a link which you can bookmark and click on any webpage to inject the necessary code to make annotations.

I tried the bookmarklet in Firefox (both PC and mobile), but it presents two major drawbacks:

1. Launching the bookmarklet is not as straightforward as clicking an extension button. It is true that a shortcut can be added to the bookmark toolbar, but I prefer to hide this toolbar to allow more space for browsing. In addition, this toolbar is not available (and it would take too much space if it were) for mobile.
2. When launched from a bookmarklet, the Hypothesis client isn’t working in webpages with Content Security Policy (CSP) enabled, such as GitHub and Internet Archive’s Wayback Machine (you can read more about this issue here). Many webpages rely on resources (scripts, fonts, etc) hosted elsewhere. CSP is a security measure which tells the browser from which sources it can fetch additional resources, to make sure only trusted resources can be loaded onto the webpage. Update July 23rd, 2019: Apparently this will be fixed in Firefox 69.

In this guide I will explain what I think is the best way to use Hypothesis in an Android cellphone (although I guess it may work in iOS too), using Firefox. The cool thing is these instructions will work for both PC and mobile versions of the browser.

It is worth noting that another option to use Hypothesis in a cellphone is by installing Yandex, a browser based based on Chrome (Chromium, to be accurate), available both for Android and iOS. As opposed to mobile versions of Google Chrome, this browser does work with Chrome extensions, including Hypothesis’. However, I haven’t played much with the browser myself, so that’s all I can say about it. U̶̶̶̶p̶d̶a̶t̶e̶ ̶J̶u̶n̶e̶ ̶3̶r̶d̶,̶ ̶2̶0̶2̶0̶:̶ ̶C̶h̶r̶i̶s̶ ̶A̶l̶d̶r̶i̶c̶h̶ ̶p̶u̶b̶l̶i̶s̶h̶e̶d̶ ̶a̶n̶o̶t̶h̶e̶r̶ ̶i̶n̶t̶e̶r̶e̶s̶t̶i̶n̶g̶ ̶o̶p̶t̶i̶o̶n̶ ̶h̶e̶r̶e̶,̶ ̶u̶s̶i̶n̶g̶ ̶t̶h̶e̶ ̶U̶r̶l̶ ̶F̶o̶r̶w̶a̶r̶d̶e̶r̶ ̶a̶p̶p̶ ̶a̶n̶d̶ ̶t̶h̶e̶ ̶V̶i̶a̶ ̶p̶r̶o̶x̶y̶. (Update June 21, 2021: Unfortunately, most websites are no longer supported by the Via proxy).

1. How to easily activate Hypothesis on all webpages?

After installing Firefox, a way to easily activate Hypothesis on all webpages, without having to find and launch the bookmarklet, is using a userscript manager, such as Greasemonkey. Update January 29th, 2021: As mentioned by Kostis in the comments below, a simpler way is to just install Hernawan Faïz Abdillah’s bookmarklet extension. To do this in the new Firefox for Android, you have to use Firefox Nightly and follow the instructions here.

Greasemonkey is a Firefox addon that lets you run custom JavaScript code on the pages you visit. To install it, go here and click on “Add to Firefox”.

Once installed, you can install a script I wrote based on the Hypothesis’ bookmarklet. To get it, go here and click “Install” on the window that will pop up. Feel free to check the code and suggest changes if you wish!

All set: the Hypothesis client should now be enabled on all webpages you visit. If you want to disable it for any particular site, just add it to the “User excludes” in the Greasemonkey menu (Update January 13th, 2020: Facebook seems to slow down with the script; you may want to add https://www.facebook.com/* to the exclude list to avoid this).

Update April 30th, 2020: tim improved the script a bit, including some useful exceptions, and published it for Greasy Fork and Greasemonkey here.

2. How to make Hypothesis work in sites with CSP enabled?

As mentioned above, when launched from the bookmarklet the Hypothesis client isn’t working on webpages with Content Security Policy (CSP) enabled, such as GitHub and Internet Archive’s Wayback Machine. Update July 23rd, 2019: Apparently this will be fixed in Firefox 69.

One possible workaround is to disable CSP in your browser altogether, but that would be insecure.

Alternatively, you can use a browser addon to include Hypothesis as a trusted source in the CSP header of the webserver response.

To do this automatically for all webpages, I am using the Header Editor addon, which is the only Firefox addon I found which let me run a custom function on the response headers. You can get it here.

Once installed, you can write your own rule, or use the one I wrote:

1. Open the Header Editor menu.
2. Click on “Manage”.
3. Go to “Export and Import”.
4. Copy this URL, paste it in the URL field and click Download: https://raw.githubusercontent.com/diegodlh/h.csp/master/hypothesis.json
5. The “Hypothesis” rule should appear: click “Save” to apply it on all webpages you visit from now on.

Once saved, you can look the “Hypothesis” rule up in the “Rules List” section, and click “Edit” to check the code:

That’s all. I hope you find this guide useful. Feel free to add comments at the end, or using Hypothesis!

Update July 1st, 2019
Bare in mind that unfortunately, due to a change in Firefox 60 and newer, Greasemonkey user scripts are not running on the browser’s pdf.js viewer. As a result, the Hypothesis client doesn’t load automatically on PDFs, and it has to be loaded through the bookmarklet instead. See here and here for further information.