Adding Webmentions to My Static Hugo Site

As another step in bringing indieweb ideas into my site, I have added support for webmentions. If you want to mention a post on this site, you can send me a webmention via this endpoint.

A webmention is a kind of linkback. It is similar to pingbacks or trackbacks, but with a more modern sensibility that wants to extend @-mentions out of silos and to the open web.

The idea is straightforward: any URL (the source of the mention) should be able to mention any other URL (the target of the mention). The target gets to choose what to do with the mention: they can ignore it, publish it on their own site, use it to increment a counter, etc.

In order to receive webmentions you provide an HTTP endpoint that listens for mentions. After you’re able to receive mentions, you need some way to process them. This workflow could be fully manual (e.g. you read your endpoint’s logs, then write and mail thank you cards to the sources of the mentions), but automating this with some code is probably less work in the long run.

After some research, I opted for what seemed the easiest path:

1. Use webmention.io to get a free, no-hassle webmention endpoint for my domain.
2. Use webmentions.js to display the mentions received by the webmention.io endpoint on my posts.

Getting a webmention endpoint and advertising it

This site is staticly generated (I use Hugo), so there is no “running server” to which I could easily add an endpoint. I could add a CGI script to my webserver, and use that as my endpoint, but that seemed like more work than I wanted to do for this experiment.

Instead, I decided to use Aaron Parecki‘s free webmention.io service. You sign up with your domain, and voila: webmention.io gives you a personalized endpoint that friends and trolls can send mentions to.

After signing up for a webmention.io endpoint, I added a link to it from my site’s HTML header, so that anyone looking to send me a mention can discover which endpoint to use:

<!-- in HTML header -->
<link rel="webmention" href="https://webmention.io/anaulin.org/webmention" />

Displaying mentions with webmention.js

Continuing with the theme of “what is the easiest possible thing I could do”, I chose to use fluffy‘s excellent webmentions.js library to show on each post the mentions it has received.

This is a neat piece of drop-in JavaScript that knows how to query webmention.io to retrieve mentions for the current URL, and then displays them on the page. It all happens in a visitor’s browser when they load a post.

To integrate webmentions.js:

1. Include the library’s JavaScript file somewhere in your site.

<!-- in HTML header -->
<script src="/js/webmention.min.js" async></script>

1. Add <div id="webmentions"></div> wherever in your HTML you want webmentions to display.

You can add some custom CSS rules for this div, which is where webmentions.js will be adding the actual webmention content. The library’s GitHub page has good documentation on additional options.

How does it feel?

This was surprising easily to set up. The hardest part was researching what was available and what would best fit my needs. I wasn’t able to find a great “Webmention 101” guide, and instead had to spend some time sifting through the IndieWeb wiki and other websites, until I was able to form a rough idea of my options and what would work with minimal investment on my part.

The biggest disadvantage of this setup is that I don’t own any of my mentions data. If webmentions.io disappeared in a puff of smoke, I would lose access to all the mentions this site has received, in addition to no longer having a webmention endpoint. Right now this doesn’t concern me.

If over time I end up receiving a healthy amount of interesting/amusing/valuable mentions, then I’ll consider automating backing up the mentions from webmention.io. It wouldn’t be too hard to add a step to the site publishing process where I download the mentions from the server, and then store them in some structured way with each post (e.g. in the front matter).