Why I think webmentions are complex.

A breakdown of my opinion on IndieWeb mentions as they relate to static sites.

This post is in the context of a static site, but I’ll generally go over why I think webmentions are complex. This post is also a spiritual follow-up to my toot a couple of days ago.

If you’re new to IndieWeb, you can essentially replace the word ‘Webmentions’ with ‘interactions with other independent websites’ during the reading of this article.

First, let’s describe what one might want to achieve when implementing webmentions:

  • Receive interactions from IndieWeb enabled websites.
  • Send interactions to other IndieWeb enabled websites.
  • Moderate received webmentions.
  • Integrate their display into your site.

Outgoing webmentions.

This is probably the simplest part of the equation. You must ensure that your content markup adheres to IndieWeb’s (ever evolving) standards, and make POST requests to websites you are interacting with.

This adds one moving part, but does not require that you have an endpoint yourself, or that you run a Micropub server (which will often include this functionality to make things easier for authors and publishers).

This means you can have the following types of interactions with very little hassle:

You can achieve this by running an npm binary such as @remy’s webmention package against your newly published post on a freshly generated site. Still a bit of manual work because you must wait for your site to be published, grab the URL, and then run the binary — but not impossibly inconvenient.

Incoming webmentions.

This is where things start to get a little tricky. If by sending webmentions you added one additional moving part, receiving webmentions adds two additional moving parts (for a total of three now).

Now, you need:

  1. An HTTP endpoint capable of receiving and processing webmentions
  2. A moderation interface (while not required, heavily recommended)
  3. A build pipeline in your static site that is able to fetch this data and show them on pages and posts as required

While the first requirement can be a simple binary you run on a self-hosted server, or use perhaps a hosted service (such as webmention.io), you are now reliant on beyond just the parts you include in your site repository.

The second requirement can either be an extension to the first one, or a standalone application itself that interacts with the first binary. Which means…building an API and a frontend. You must also make sure to exclude invalid webmentions (maybe someone else implemented a markup on their content that doesn’t exactly work 100%).

The third requirement is for your site to fetch webmentions data from your own endpoint, cache it (so your site doesn’t go back in time because webmentions are unavailable), and build out a few templates for each webmention type.

You could also use serverless functions in place of the first requirement (building a receiving endpoint), but you’re going to need a store of some sort either way (aka a database, whether file based or relational).

Projects like webmention.io feel like a proof-of-concept rather than a polished experience iterated upon over the years.

What if I’m not using a static site?

Things should become easier as you could engineer for fewer moving parts. This is where projects like GoBlog by Jan-Lukas Else and Tanzawa by James Van Dyne become good examples.

My ideal implementation.

An application that is maintained and has tests — as well as is easy to self-host using Docker/Podman/Heroku. The application:

  • must be a single website,
  • checks my static site for new URLs routinely,
  • prompts me to send webmentions if it finds any,
  • runs a webmention receiving endpoint,
  • has a moderation interface built in,
  • is able to junk invalid webmentions, and,
  • has an endpoint for my static site generator to consume where it throws the final JSON data free of any errors, invalid webmentions, spam, unapproved webmentions, and so on.

This would be a companion service/app/website to any static site that has microformats2 markup. Because it’s a single place for webmentions for your site, it would usher in more adoption from developers who are shifting to or recommending static site generators to their colleagues and so on in the recent years. Instead of three moving parts, you add one that is convenient and gets-it-all.


I’ve been thinking about integrating post types and outgoing webmentions in my Eleventy starter kit. This post was written when I *think* I achieved a good-enough clarity on what to do.

Webmentions appears to have a varying level of complexity depending on what you want to do. Nonetheless, one-sided conversations are not fun. However, they are the easiest to implement.


Comment via email.