Webmentions are a useful way to notify a website that you have linked to it. Microformats like h-entry combined with u-in-reply-to, u-like-of, u-bookmark-of, or u-repost-of give context to the mentions.
Sending a Webmention means POST-ing to a Webmention endpoint with the data source and target. The source is the URL of the page that contains a link to the URL target. Note that a standards-compliant recipient will discard1 Webmentions if the content of the source page does not contain a “per-media-type” mention of the target URL. For example, and HTML source might contain an <a href> or <video src> matching target URL and a JSON source could contain any key whose value exactly matches target. A plain text document would need to contain the target URL verbatim.
While simply notifying a site that you’ve mentioned or linked to it is nice, without additional context the Webmention might not be very useful. Adding context using h-entry, ideally with embedded h-card and h-cite Microformats, can give the recipient more information about what the link means and potentially how to display it. For example, Hearthside (this site) via Mentionable will happily store any Webmention sent to it provided that they’re valid. Only Webmentions that contain h-entry with at least e-content or e-summary will be displayed at the bottom of the page as comments.
An h-entry is a Microformat that’s both simple to implement and powerful to consume. It gives structure to your content and allows human-readable content to be parsed by computers. While a Webmention with a source linking to
<a
href="https://www.prioritized.net/blog/testing-ruby-gems-with-github-actions"
>
tells Derek that his blog post has been linked to,
<a
class="u-reply-to"
href="https://www.prioritized.net/blog/testing-ruby-gems-with-github-actions"
>
within a blog post wrapped in a main.h-entry article.e-content that contains an .h-card gives Derek the context that Caleb has replied to his post and what the content of the reply was.
Marking up your blog with h-entry isn’t too difficult. You’ll probably want to wrap the whole page with h-entry so that you can use something like your <h1> as the h-card representing yourself as the author, wrap the content of your articles in e-content, and use the most appropriate u-* class on the <a> tag for the type of mention you’re sending.
For example, a reply would use u-in-reply-to, a like would use u-like-of, a bookmark would use u-bookmark-of, and a repost would use u-repost-of. If you want to go above-and-beyond, each of those u- types can also be an h-cite that can give even more structure to the post. The simplest h-cite would be something like <a class="h-cite u-url" href="https://www.prioritized.net/blog/testing-ruby-gems-with-github-actions">Testing Ruby Gems with GitHub Actions</a> but there are plenty of other properties that can be used to give even more context to the mention.
It would be nice if Markdown had a shorthand for adding classes to links, but for the time being doing this means hand-writing the HTML for links into your Markdown files so that you can add the classes. A basic example could be to say that “I really like ’s blog post from on testing Ruby gems with GitHub Actions”.
<span class="h-cite p-content">
I really like
<span class="p-author">Derek Prior</span>'s
blog post from
<time datetime="2020-04-10" class="dt-published">2020</time>
on
<a
class="u-like-of p-name"
href="https://www.prioritized.net/blog/testing-ruby-gems-with-github-actions"
>
testing Ruby gems with GitHub Actions
</a>
</span>
Automating Sending Webmentions
Personally I get a lot of value out of Robb Knight’s [Echofeed] service to take my feeds and turn them into Webmentions as well as Mastodon and Bluesky posts. Echofeed’s Webmention service takes a feed as input and I believe it fetches the URL of each feed item to check for outbound links, looks for a Webmention endpoint at each of those links, and sends Webmentions if it finds one.
Much more common especially among folks with statically generated blogs is to use webmention.app to send Webmentions by hooking into your build process and sending a request to the webmention.app API for each changed page on their site.
Of course, you can also send Webmentions manually, but finding every link, polling for a Webmention endpoint, and sending the POST request would be tedious at scale.
Bonus: Receiving Webmentions
I use Mentionable to receive Webmentions and extract h-entry data from them. If you’re using Rails or Ruby, please give it a shot. I also use Brid.gy is another popular service that polls social media sites like Mastodon, Bluesky, and Reddit for mentions of your site and sends them to your Webmention endpoint.
I read very good things, again generally from folks using static site generators, about Webmention.io to send Webmentions.