Understanding Webmentions

README.md

Webmentions

A webmention is a way for one website to communicate with another. A webmention requires three things:

1. One site must have and host a webmention.
2. That webmention must link to a real location on another site.
3. That other site must accept webmentions.

The location of the hosted webmention is referred to as the source. The location being linked to is referred to as the target.

If the site accepting webmentions requires those requests are sent to a particular location, this location is referred to as the endpoint. An endpoint may be found in the source code of a site by searching for a rel attribute with a value of webmention.

There are two common ways to find the webmention endpoint:

<link href="/webmention" rel="webmention">

<a href="/webmention" rel="webmention">Send a response</a>

Writing a webmention

... explanation pending

Below is an example of a webmention. This markup would be found in the contents of a source URL.

<p class="h-entry">I was reading <a href="{{target}}">{{target}}</a> at <time class="dt-published" datetime="{{datetime}}">{{datetime}}</time>.</p>

Below is an example of a like:

<p class="h-entry">I like <a class="u-like-of" href="{{target}}">{{target}}</a> at <time class="dt-published" datetime="{{datetime}}">{{datetime}}</time>.</p>

Below is an example of a repost:

<p class="h-entry">I reposted <a class="u-repost-of" href="{{target}}">{{target}}</a> at <time class="dt-published" datetime="{{datetime}}">{{datetime}}</time>.</p>

Finally, below is an example of a reply.

<article class="h-entry">
	<header>
		<h3 class="p-name"><span>in reply to</span> <a class="u-in-reply-to" href="{{in_reply_to_link}}">{{in_reply_to_link}}</a></h3>

		<p><span>by</span> <a class="p-author h-card" href="{{author_link}}"><img class="u-photo" src="{{author_image}}" alt=""> {{author}}</a></p>
	</header>

	<div class="e-content">
		{{comment}}
	</div>

	<footer>
		<p>Published <time class="dt-published" datetime="{{datetime_precise}}">{{datetime}}</time></p>
	</footer>
</article>

Sending a webmention

Mentions are sent with a POST method request. The POST request sends two fields, source and target. It may optionally send a third, callback.

POST {
	"source": URL
	"target": URL
	"callback": URL
}

The source is the URL containing the webmention. The target is the URL being webmentioned. The callback is the URL to be redirected to after sending a webmention.

Once the page receives the webmention, it reads the contents of the source URL and looks for specific element identified as a webmention.

The selector that is used to match a webmention is [href="target"], with target being the source URL. A valid webmention must be a child of an element matching .h-entry, which itself must also contain a .dt-published element.