I write margin notes while reading books. They help me keep my thoughts on record and within context. But how do I do that on a website or an ebook?

Marginalia in Truth and Beauty — S. Chandrasekhar

This is an experiment in implementing a marginalia (or annotation) system using the principles of the indieweb. The broad idea is to allow readers to write notes/comments that link to a particular part in my article and then notify me so that I can display a copy approriately in the right place.

The post-artifact web

Craig Mod wrote a beautiful article about Post-Artifact Books & Publishing talking about the problem of marginalia for ebooks. I highly recommend you read it. The artifact is the ‘final’ produced content — a book, an article, a magazine. The pre-artifact includes the process of creating and editing ideas to generate the content. In the case of digital content, the artifact, once created and published, is not static. Apart from further edits by the author, readers can add their own thoughts through comments, sharing, and sometimes marginalia.

This is the post-artifact system. A system of unlocking. A system concerned with engagement. Sharing. Marginalia. Ownership. Community. And, of course, reading.
—Craig Mod

Some publishers already have a kind of post-artifact system. As Craig notes, Amazon allows you to post and share public notes for the books you’ve bought on the Kindle. Medium allows you to post marginalia using your Twitter account. Such systems miss an important aspect of the process — ownership. Your notes/marginalia exist on some third-party system, not your own site.

Two things are necessary for true innovation and engagement to happen in this space:
  1. A well defined and open protocol. It is to this which all software and tools built to engage the post-artifact space can connect.
  2. The ability to construct canvas independent hooks beyond the reading space.
—Craig Mod

The folks at indiewebcamp has already tackled this issue for web-based (i.e. HTML) content — the protocol is webmention and hooks are microformats. You can post a reply or comment (markedup with microformats) on your own site and choose to notify the original content (through webmention) by linking to it. This way the original comment exists on your own space (and under your control) while the original content gets a copy to display as it chooses.

This same idea could be adapted to marginalia that lives on the readers’ site; the missing piece of the puzzle is to have a way to refer to a part of the post with a URL.


This is where Kevin Marks’ fragmentions come in. Fragmention1 is a way to refer to an arbitrary piece of text on webpage by just appending it to the URL; for instance to refer to “some random text” on “” you’d use the URL

Jonathan Neal has already written a fragmention javascript that given a fragmentioned URL, finds the text and scrolls you to that part of a webpage.

But it is possible to use this not just to find and scroll to a text phrase, but also to refer to it from a comment. So if you sent a webmention to the URL of the post it will be treated as a comment to the whole post. But if you send it to a fragmentioned URL, then it will be treated as marginalia to that part of the post!

Federated marginalia — pretty awesome if you ask me!

Display & UX

So what would such a marginalia-enriched content look like? This article is an experiment at such a post.

By default the marginalia are treated just like normal comments, but their u-in-reply-to is set to the appropriate fragmention. This provides a safe default on which some javascript magic can act. If the javascript is active, the marginalia are moved to the content to which they refer. A small icon appears next to the content containing the marginalia which then toggles the visibility of the marginalia.

The visual display and the related UI/UX is something I am still playing around with. At the Indiewebcamp 2014-East, I finished up a prototype UI for this. At smaller screens, the marginalia just appears below the content paragraph, and on longer screens it appears on a scrollable side-panel.

I have put up the marginalia.js javscript on github2. The javascript and the CSS styles are mostly independent, so you could implement your own UI for marginalia on your own site! Let me know if you do something with this on your site.