A Powerful Partnership Brings Open Annotation to EPUBs

By Nate Angell | 21 September, 2017

Today, Hypothesis and our partners, NYU Press and NYU Libraries, the Readium Foundation, Evident Point and EPUB.js, are announcing the world’s first open-source, standards-based annotation capability in an EPUB viewer — or rather two EPUB viewers, because we’re launching with identical functionality in the two most popular open-source frameworks, Readium and EPUB.js. For the first time, publishers and others now have a complete annotation solution for all their content published in all three primary digital formats: HTML, PDF and now, EPUB.

A large EPUB logo, surrounded by logos for NYU, EPUB.js, the Readium Foundation, Evident Point, and Hypothesis.

This means that anyone who wants to make an annotatable EPUB available can do so using their choice of reading frameworks, giving readers the ability to take personal notes, group notes or have public discussions on top of the fastest growing web standard text format. As with PDFs, those annotations will synchronize across copies of the same EPUB hosted in different places and even within different readers.

Also, if cross-format identifiers like DOIs are used, annotations made in one format (eg, EPUB) can be seen in the same document published in other formats (eg, HTML, PDF) and in other locations. All annotation capabilities of Hypothesis, including groups, markup, rich media, math support, and more are now available across all three formats — HTML, PDF, and EPUB. For example, annotation groups active in different formats and different locations can be available to group members on the same documents accessed anywhere. Annotations that users make in EPUBs are searchable and discoverable together with all their annotations made in other documents and formats.

Try annotating yourself in these live examples: in Moby Dick, delivered with Readium, and in the same book delivered with EPUB.js. Both examples show how annotatable EPUBs can be embedded directly in webpages or linked to provide more focused, standalone reading experiences. Note that as you annotate in one reader, the same annotation will immediately be visible in the other. Feel free to add your own test annotations: we’ve modified the fingerprint in these demos so that annotations in them will not clutter the original EPUBs. If you’d like to try annotating your own EPUB, drag and drop your file on the target at docdrop.org.

Readium Demo
EPUB.js Demo

A powerful partnership

The success of this collaboration highlights the benefits of a community development model using leading open-source, standards-based components. This approach to software and product development combines open-source modules already in wide use and leverages their user base to serve more people, at lower cost, while reducing product fragmentation and lock-in.

A few notable accomplishments include:

Thanks to significant contributions from Evident Point, the Hypothesis annotation framework now has the ability to create and anchor multiple iframes on a single web page. Prior to this work, the Hypothesis client recognized the top-level document (in other words, the parent website) as the content to be annotated, and not the EPUB served in an iframe by a reader like Readium or EPUB.js. Now, Hypothesis can detect multiple frames and inject the sidebar code into each frame as appropriate. Lines of communication between the frames are also opened, and the sidebar can be shown or hidden from any iframe on the web page. This innovation extends beyond EPUBs to open the door to enabling annotation in an even wider array of digital contexts with multiple iframes, including applications that offer content creation and editing.

Another challenge overcome was accommodating the unique way EPUB readers display pages. Because users “turn” the page to view more content, we needed to add support for letting the EPUB reader handle events which are usually done by Hypothesis. This means that following a direct link to an annotation works in EPUBs which was a primary goal of the team. Additionally, the annotation adder (the “annotate” or “highlight” button that appears when you highlight text while Hypothesis is active) was modified to handle presentations two columns of text.

To enable a book to mirror annotations made in an identical copy elsewhere, we combined existing EPUB document and section (chapter) identifiers and exposed them to the Hypothesis client. This enables annotations to be scoped according to chapter, and annotations can be dynamically loaded, appearing in the sidebar of other copies of the same EPUB based on the current chapter.

The teams also made several other improvements to the Readium reader specifically to improve support for annotation. We modified Readium’s URL parameters to support direct linking from Hypothesis activity pages to the Readium environment. Hypothesis also now includes options for configuring the placement of its sidebar to alleviate problematic overlapping of Hypothesis and Readium elements in the user interface.

The next version of EPUB.js provides Hypothesis with the necessary identifying information about a book by default, allowing any ebook readers that uses EPUB.js for rendering to support annotations just by adding the Hypothesis embed script.

Work still underway includes a better way to anchor annotations: EPUB documents are sensitive to changes to their element structure, since these affect their native anchoring scheme (the Canonical Fragment Identifier). In response to this issue, Hypothesis is implementing an overlay highlighter to replace the current highlighter that injects tags into documents. The teams will also continue work to add support for the page notes feature in Hypothesis and the continuous scroll mode setting in Readium.

Annotation in EPUBs is made possible by standards developed by the W3C Web Annotation Working Group and IDPF. For the anchoring approach, we leveraged the existing Hypothesis fuzzy anchoring technology. In the future we plan to implement support for Canonical Fragment Identifiers (CFIs).

Share this article