Implementing Web Mentions


How to claim back mentions from social media

The premise of Web Mentions is very simple: gather mentions of content you’ve created—likes, replies, reposts & more — from all over the web and display them on your own website.

Peeke Kuepers

Web Mentions are build on the indie web, which is — in their own words — a people-focused alternative to the corporate web. It’s a movement which aims to give indie web creators like you and me control over our own content again.

And that's exactly what Web Mentions do. Websites or third party services implementing them notify you when anyone mentions a url pointing to your site. You can then aggregate these mentions and display them with the relevant piece of content on your own website. 

The interesting part to me was leveraging this technology to turn Twitter into a comment system for my articles. A lot of the discussion regarding frontend development takes place on Twitter, so I figured it's the perfect platform for comments on the topic. And most of the people looking to comment on my articles probably already have a Twitter account as well. 

Since most of the articles about Web Mentions only describe how the API works on a higher level, I decided to document to process of adding them to my own site in this article. If you're actually interested in a more high-level overview of the technology, you can read Drew McLellan's excellent article Implementing Webmentions.

Now, let's get cracking.

First things first. You need to IndieWebify your website. In practice, indiewebifying your site means adding a bunch of meta information to your HTML. This makes your site indexable for robots, so they know when to give you an update regarding a new mention.

Web signin

Venturing into the indie web, the first step is to link your social media accounts on the web, to provide some information about who you are. You do this by adding a link with rel="me" on your site linking to the profiles you want to associate with your site. You should also link back to your website from the respective social media profiles to validate it's really you.

Adding your ‘business card’

To indicate the author of your site (you, duh!) or an individual article, you have to add a so called h-card to your index and article pages. The h-card contains general information like your name, profile picture and site url. You can find the full list of allowed properties over at the microformats wiki

In my case, I kept it simple and used the h-card below:

<p class="h-card scr">  
<img class="u-photo" src="//" alt=""/>
<a class="p-name u-url" href="//">Peeke Kuepers</a>

I’ve actually hidden this information for regular visitors, since I only publish my own articles on here.

Your entries and entry feed

The content of your articles should be marked up in the h-entry microformat. Among other properties, the h-entry highlights the title, content, summary and author of an article. You can also provide links to re-posts of this article elsewhere on the web. 

The structure I ended up with after marking up my articles looks a bit like this:

<article class="... h-entry">
<header class="p-summary">
<h1 class="... p-name">An elastic bounce one liner</h1>
<p>Creating a custom easing function</p>
<p>You know that feeling when you try to ...</p>
<span class="p-author h-card scr">
<img class="u-photo" src="//" alt=""/>
<a class="p-name u-url" href="//">Peeke Kuepers</a>
<a class="u-syndication"
(Re)published on
<time datetime="2017-1-8 21:48">
8-1-2017 21:48
<div class="e-content">...</div>

Finally, we need to format our index page according to the h-feed microformat. This is used to link to all our content entries from the index page. The h-feed is pretty basic: it contains the feed title, your h-card, the feed url and — most importantly — a bunch of h-entries.

The feed on my site looks like this:

<div class="h-feed">
<span class="p-author h-card" hidden>
<img class="u-photo" src="//" alt=""/>
<a class="p-name u-url" href="//">Peeke Kuepers</a>
<a href="/" class="a-url" hidden></a>
<h1 class="p-name">My blog</h1>
<article class="h-entry">...</article>
<article class="h-entry">...</article>

Now you’ve done all these things I’ve got to break it to you: 

Twitter, Facebook and  most other media platforms do not support Web Mentions

Sad face. Luckily for us most of them do offer API’s to access and search their content for mentions. The awesome people at decided to use this to bridge this gap in functionality (pun intended, of course).

First login to using social login. The next step is to link your website by entering your website in your social media profile. Conveniently, you already did this when you were indiewebifying yourself.

In your dashboard displays a few options:

  • Crawl your site: crawling indexes your website and discovers the original content on it. For this step it’s important you’ve marked up your content as described above.
  • Poll for mentions. Polling means performing a search on Twitter for mentions of your content known to
  • Check a post. This means checking a specific post for replies, likes and reposts.

Whenever finds a mention, it will gather the required information and send it to the endpoint of the entry. It won’t happen instantly — more like once every 30 minutes — but it works quite well. And it’s a free service!

Syndicating your content

Syndicating sounds fancy, but it’s actually really simple. It means indicating to the indie web that content somewhere else on the web — for instance a Tweet — is a copy of the original post on your website. To do this, you place a list of syndicated links on the relevant content entry on your site.

<a href="" class="u-syndication">

Syndicating a tweet requires that the Web Mentions server (in this instance can find a link from your Twitter profile page to your website. You can also syndicate reposts of your content on other sites (if those sites send out Web Mentions). In this case an a tag with a rel="shortlink" should be included in the re-post, pointing to your original article.

Having a look at the W3C page for Web Mentions you can see that handling incoming mentions yourself is no trivial task. Things get complex quickly when you consider updating and removing content. This is where steps in. is a cloud service which handles incoming Web Mentions for you. Instead of placing a unique Web Mention endpoint on every one of your pages, you just paste an endpoint provided by

In my case: 

<link rel="webmention" href="" /> takes care of collecting mentions and keeping them all up to date. As an added bonus also easily lets you delete mentions, making moderation a breeze. To gather your mentions from the service you just make a request to an endpoint they provide. In response they  send you a nicely formatted piece of JSON, which is yours to do with as you please.

Of course you should really cache the response you receive. Since only checks your mentions at most once every 30 minutes it doesn’t make sense to send a request to for each visit. You don’t want to DDOS them in case your article goes viral.

Happy coding

That's all there is to it. Now go fire up your editor and collect yourself some fine Web Mentions! 


Appendix: Being a good internet citizen you should also send out a web mention to other people’s site if you mention their content! I'd recommend looking into webmention-client on NPM.

Liked this article?

Why not follow me on Twitter? @peeke__.