Semipad, a calibre-web mod for collaborative annotations

As part of the Critical Technical Practice project of the DARC research center at Aarhus University, Martino Morandi and me got invited to help think and design the on-line DARC Library. This library facilitates reading groups and their annotation practices.

Based on exchanges with the DARC group, we came up with an idea to combine Calibre-web with Etherpad-lite. Calibre-web allows one to share and organize digital publications, as well as read them in the browser. Etherpad-lite is a tool for collaborative note-taking. Mushing them together, we created what we call semipad. The name derives from having half¹ a screen of text, and a pad. With it, one can read a publication in the browser and take notes at the same time. The notes have no one owner and persist alongside the text. Annotations are thus shared and live along side the document. A bit like reading someone else’s marginalia in a book you got from the library.

We have little desire to maintain semipad as an up-to-date fork of calibre-web. So, this post describes exactly what the modification does so that others can reproduce the modification themselves.

The whole mod requires several components set up first:

• an installation of etherpad (ideally on the same domain)
• a webserver that can redirect requests
• a modified version of calibre-web.

The whole mod is based on the fact that in etherpad-lite, new pads can be made by just creating a URL to a pad. So if an etherpad-lite installation can be accessed under the URL https://ctp.cc.au.dk/pad/, then following a link to https://ctp.cc.au.dk/pad/p/mynewpad will automatically create a pad called mynewpad if it doesn’t exist². If it already exists, you open that pad.

At the same time, in calibre-web publications are assigned an identifier that is unique to each uploaded book. This UUID will look something like bb22b17c-aa7c-4873-ab60-84f59c735c8c.

By passing calibre-web’s book UUID as a parameter in the etherpad-lite URL, one can associate a pad to a book: https://ctp.cc.au.dk/pad/p/bb22b17c-aa7c-4873-ab60-84f59c735c8c.

Finally, how this was integrated was by adding a button to each book detail view, which resolves the pads. It is based on the one that normally opens the html PDF reader and takes the book UUID as an argument. In our modification, this reader not only loads the PDF associated with the UUID, but also an iframe with the source “/pad/p/UUID”. Then there is some CSS which styles everything properly. Finally, we modify the CSP to allow iframes³.

Conceptually, these three lines are the extent of the hack. The rest of the code just passes around variables to make it work!

The source code is available at https://gitlab.com/jeweyjacobs/calibre-web-semipad/. However, take care as it is half-abandonware! The repository linked is an older version of calibre-web, that in the meantime has been updated. The daring ones that want to run semipad should not clone and install this repository, but rather repeat the steps in these three commits to port the modification to an up to date version of calibre-web.