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.

Send me (Learn more)


  1. Ryan Barrett
    replied on to ##The+visual+display with

    totally! kyle hit the nail on the head: this is a great new feature and tool in its own right, and also a powerful demonstration of how big new things can emerge from simple, orthogonal standards without any new or modified protocols. nice work!

    i can’t wait to see a version that tries to render marginalia directly next to the part of the post they’re addressing, whether in the actual margin or otherwise. excited!

  2. Barnaby Walters
    replied on to ##By+default+the+marginalia+are+treated with

    @kartik_prabhu amazing work overall! This is one of my favourite parts though — the fact that fragmention comments fall back gracefully if they’re not supported on either side, and yet all the data required to present them is preserved, so future updates can retro-actively put old marginalia in the right place!

    I wonder how tricky it would be to implement this on the comment publisher side too — detecting fragmention URLs and tailoring the reply context content…

  3. Prateek Varshney
    replied on Google+ with
    Wow man, this is supercool! People were discussing similar an idea sometime back and voila your implementation, awesome it is :-)Keep coming the interaction on this, people replying to people’s comments and all that and pages will be so super awesome!I’m imagining Brian Koberlein adding the js to his site and people like me asking questions when going blank and people replying to them and me getting notification for such replies.. go for it! (Or the better directions you maybe looking into)