Hypothes.is Aggregator ― A WordPress Plugin

I’ve been working and writing a lot lately about using the web annotation tool hypothes.is for public scholarship. It has a lot of cool uses ― not only the collaborative annotation of individual web pages, but also the creation of a public research notebook, and the possibility of linking hypothes.is with other apps through the use of their open API.

Based on that work, I’ve created a few tools to help people make fuller use of hypothes.is in their work as public scholars. The first is a Python script that collects annotations (by user, by tag, or both) and converts them to clean MarkDown text, for use in a blog. The second is Pypothesis, a Python module for writing programs that interact with the hypothes.is API.

More recently, I’ve created a WordPress plugin called Hypothes.is Aggregator, which will allow WordPress users ― bloggers, teachers, and students alike ― to collect their own annotations, annotations on a topic of interest, or annotations from/about a class, and present them in a page or post on the WordPress platform. It’s easy to install, easy to use, and (I hope) will be of value to students, scholars, teachers, and writers.

How it works

Hypothes.is aggregator is super-simple. Create a new page or post in WordPress, and as you write, include the following “shortcode”:


Now, that alone won’t do anything. You need to feed it some search terms, like one of the following:

[hypothesis user = 'kris.shaffer']

[hypothesis tags = 'IndieWeb']

[hypothesis text = "Domain of One's Own"]

[hypothesis user = 'kris.shaffer' tags = 'IndieEdTech']

Hypothes.is Aggregator accepts user, tags, and text search parameters, on their own or in combination with each other. (Currently it does not support lists of users or tags, but that is in the works for a future version.)

After adding one line of this “shortcode,” publish the post, and you should see on that page a list of annotations, like on this sample page. That’s it!

(If it doesn’t work, please let me know, and I’ll do my best to figure it out and release a fix.)

What it’s for

I envision a number of possible uses for Hypothes.is Aggregator. As I write in my post on hypothes.is as a public research notebook, you can use this plugin to make a public research notebook on your WordPress site. Read something interesting, annotate it, and aggregate those annotations ― perhaps organized by topic ― on your domain. They will automatically update. Just set it and leave it alone.

I also see this as a tool for a class. Many instructors already use hypothes.is by assigning a reading that students will annotate together. Hyopthes.is Aggregator makes it easy to assign a topic, rather than a reading, and ask students to find their own readings on the web, annotate them, and tag them with the course tag. Then Hypothes.is Aggregator can collect all the annotations with the class tag in one place, so students and instructors can see and follow-up on each other’s annotations. Similar activities can be done by a collaborative research group or in an unconference session.

Help me kick the tires

I’ve done a lot of small tests, but I could use some help. So if you’re interested, please try it out and let me know how it goes. I’ll do my best to help you out and/or add fixes and features to future versions.

It’s really easy to install and get going. First, go to the project page on GitHub, click “Clone or Download” (the green button on the right), and then “Download to ZIP.” Then go to Plugins >> Add New in your WordPress dashboard. Click “Upload Plugin.” Then upload the ZIP file you just downloaded. Once it’s uploaded and installed, click “Activate,” and you’re ready to go!

Then try it out, and let me know how it goes.

Plans for the future

It can do a lot of things as-is. But I want to add more. Here’s my current list (feel free to suggest more):

  • Search for all posts from a list of users (for more fool-proof class aggregation).
  • Support multiple tags ― in both AND and OR configurations.
  • Add “class” attributes to the HTML objects, for more flexible visual presentation.
  • The ability to embed a single annotation into a blog post (like you can with a tweet).

What else should this plugin do?

Photo by darkday (CC BY 2.0).