#webmention
-
Sending your First Webmention from Scratch
Webmention is one of the fundamental indieweb building blocks. It enables rich interactions between websites, like posting a comment or favorite on one site from another site. This post will walk you through the simplest way to get started sending webmentions to other sites so that you can use your own site to join the conversations happening on the Indie Web.
So what do you need to walk through this tutorial? We'll use static files and simple command line tools so that you can easily adapt this to any environment or programming language later.
Get started
First, we'll create a new HTML file that we'll use to contain the comment to post. At the very minimum, that file will need to contain a link to the post we're replying to.
<!doctype html> <meta charset="utf-8"> <title>Hello World</title> <body> <p>in reply to: <a href="https://aaronparecki.com/2018/06/30/11/your-first-webmention">@aaronpk</a></p> <p>Trying out this guide to sending webmentions</p> </body>
Go ahead and copy that HTML and save it into a new file on your web server, for example: https://aaronpk.com/reply.html. Take your new post's URL and paste it into the webmention form at the bottom of this post. After a few seconds, reload this page and you should see your post show up under "Other Mentions"!
Making it look better
That's a great start! But you might be wondering where your comment text is. To make your comment show up better on other peoples' websites, you'll need to add a little bit of HTML markup to tell the site where your comment text is and to add your name and photo.
Let's take the HTML from before and add a couple pieces.
<!doctype html> <meta charset="utf-8"> <title>Hello World</title> <body> <div class="h-entry"> <p>in reply to: <a class="u-in-reply-to" href="https://aaronparecki.com/2018/06/30/11/your-first-webmention">@aaronpk</a></p> <p class="e-content">Trying out this guide to sending webmentions</p> </div> </body>Note the parts added in green. These are Microformats! This tells the site that's receiving your webmention where to find specific parts of your post. We first wrap the whole post in a
<div class="h-entry">to indicate that this is a post. Then we add a class to the<a>tag of the post we're replying to, as well as a class to the element that contains our reply text.Now, take your URL and paste it into the webmention form below again. After a few seconds, reload the page and your reply should look more complete here!
Now we see the text of the reply, and also notice that it moved out of the "Other Mentions" section and shows up along with the rest of the replies!
Of course this web page still looks pretty plain on your own website, but that's up to you to make it look however you like for visitors visiting your website! As long as you leave the
h-entryand other Microformats in your post, you can add additional markup and style the page however you like!Adding your name and photo
Let's make the comment appear with your name and photo now! To do this, you'll need to add a little section to your web page that indicates who wrote the post.
In Microformats, the author of a post is represented as an
h-cards. Anh-cardis another type of object likeh-entry, but is intended to represent people or places instead of posts. Below is a simpleh-cardthat we'll add to the post.<div class="h-card"> <img src="https://aaronpk.com/images/aaronpk.jpg" class="u-photo" width="40"> <a href="https://aaronpk.com/" class="u-url p-name">Aaron Parecki</a> </div>
When we add this
h-cardinto the post we've written, we need to tell it that thish-cardis the author of the post. To do that, add the classu-authorbefore theh-cardclass like the example below.<!doctype html> <meta charset="utf-8"> <title>Hello World</title> <body> <div class="h-entry"> <div class="u-author h-card"> <img src="https://aaronpk.com/images/aaronpk.jpg" class="u-photo" width="40"> <a href="https://aaronpk.com/" class="u-url p-name">Aaron Parecki</a> </div> <p>in reply to: <a class="u-in-reply-to" href="https://aaronparecki.com/2018/06/30/11/your-first-webmention">@aaronpk</a></p> <p class="e-content">Trying out this guide to sending webmentions</p> </div> </body>Now when you re-send the webmention, the receiver will find your author name, photo and URL and show it in the comment!
Great job! If you've successfully gotten this far, you're now able to comment on things and even RSVP to events using your own website!
One more detail that you'll want to include on your posts is the date that your post was written. This will ensure the receiving website shows the correct timestamp of your post. If you eventually incorporate this into a static site generator or CMS where you show a list of your replies all on one page, then you'll also want to add a permalink to the individual reply in this post. Typically an easy way to solve both is with the markup below.
<a href="https://aaronpk.com/reply.html" class="u-url"> <time class="dt-published" datetime="2018-06-30T17:15:00-0700">July 30, 2018</time> </a>
We can add that to the post below the content.
<!doctype html> <meta charset="utf-8"> <title>Hello World</title> <body> <div class="h-entry"> <div class="u-author h-card"> <img src="https://aaronpk.com/images/aaronpk.jpg" class="u-photo" width="40"> <a href="https://aaronpk.com/" class="u-url p-name">Aaron Parecki</a> </div> <p>in reply to: <a class="u-in-reply-to" href="https://aaronparecki.com/2018/06/30/11/your-first-webmention">@aaronpk</a></p> <p class="e-content">Trying out this guide to sending webmentions</p> <p> <a href="https://aaronpk.com/reply.html" class="u-url"> <time class="dt-published" datetime="2018-06-30T17:15:00-0700">July 30, 2018</time> </a> </p> </div> </body>Automatically sending webmentions
The last piece to the puzzle is having your website send webmentions automatically when a new post is created.
This part will require writing some code in your particular language of choice. You'll start by making an HTTP request to get the contents of the page you're replying to, then looking in the response for the webmention endpoint.
We can simulate this on the command line using curl and grep.
curl -si https://aaronparecki.com/2018/06/30/11/your-first-webmention | grep rel=\"webmention\"
The response will include any HTTP
Linkheaders or HTML<link>tags that have a rel value of "webmention".Link: <https://webmention.io/aaronpk/webmention>; rel="webmention" <link rel="webmention" href="https://webmention.io/aaronpk/webmention">
If you get more than one, the first one wins. You'll need to extract the URL from the tag and then send the webmention there.
Sending a webmention is just a simple
POSTrequest to the webmention endpoint with two URLs: the URL of your post (source) and the URL of the post you're replying to (target).curl -si https://webmention.io/aaronpk/webmention \ -d source=https://aaronpk.com/reply.html \ -d target=https://aaronparecki.com/2018/06/30/11/your-first-webmention
The only significant part of the response is the HTTP response code. Any
2xxresponse code is considered a success. You'll most often receive either a202which indicates that the webmention processing is happening asynchronously, or if the receiver processes webmentions synchronously and everything worked, you'll get a201or200.In practice, you'll probably use a library for discovering the endpoint and sending the webmention, so here are a few pointers to start you out in a variety of languages.
Hopefully this guide was helpful to get you going in the right direction!
If you want to dive into the weeds, check out the Webmention spec as well as more details on reply posts.
When you want to put your automatic webmention sending implementation to the test, try sending webmentions to all of the links on the test suite, webmention.rocks!
If you have any questions or run into any issues, feel free to ping me or anyone else in the IndieWeb chat!
-
hosting Homebrew Website Club SF tonight @MozSF!
RSVP http://tantek.com/2018/080/e1
Special guest @aaronpk will demo his #IndieWeb reader setup!
https://aaronparecki.com/2018/03/12/17/building-an-indieweb-reader built on #openweb standards #WebSub #Microsub #microformats2 #IndieAuth #MicroPub #Webmention #Webhooks -
Two exciting #openweb announcements today!
🎂 We're celebrating 1 million webmentions! https://snarfed.org/1-million-webmentions
🎉 Our @W3C WebSub REC and IndieAuth NOTE were just published! https://aaronparecki.com/2018/01/23/34/w3c-websub-indieauth -
Day 75: Improvements to the Webmention Wiki Page #100DaysOfIndieWeb
I've been feeling like the Webmention page on the IndieWeb wiki doesn't do a very good job of explaining what Webmention does for users, and jumps too quickly into spec details. I would like to be able to direct people at this page when I am talking to them online about what Webmention can do, which often means what I am trying to show them is how Webmention can be used to display comments and other interactions on a website. Today I started to make some incremental improvements.
I rephrased the introduction section to start with user-facing features, rather than be a description of the protocol. Starting by updating the first sentence to describe the end result rather than a summary of the of the spec. Previously, the first sentence was:
Webmention is a simple way to notify any URL when you link to it on your site.
The problem with the original definition was it only describes one side of what Webmentions do (sending) and doesn't talk about receiving. Most importantly, it doesn't actually tell you why you would want to use it.
I changed that to:
Webmention is a protocol that enables conversations across the web.
I'm no expert at writing or branding, but I think this is an improvement because it starts off by describing the end result. Feel free to offer suggestions for alternatives though!
Interestingly, the second sentence was already great, and now flows nicely after this high-level description.
This powerful building block is used for federated comments, likes, reposts, and other rich interactions across the decentralized social web.
I then went through a bunch of the IndieWeb Examples of sites that support Webmention, found illustrative examples of their sites displaying comments, and uploaded a bunch of screenshots to the wiki. My hope is that this will help people understand the end result of supporting Webmention, which is that discussions can take place across websites.
I cleaned up the bottom section of the page a bit, consolidated the "Resources" section which had previously been split out into new pages, and I found two quotes from some of the linked articles I liked which I pulled snippets of into the page.
My ultimate goal with this is to improve the webmention.net page to be something I feel good about sending people to to get an idea of what Webmention is. Now that we are starting to expand greater into generation 2, we need to improve the documentation of the various IndieWeb components to focus less on code and protocols, and more on the end goals.
I want to start by cleaning up the Webmention page on the wiki, and I would love more help with that part of it. Feel free to continue editing the copy, improving the information hierarchy, and anything else you can think of to make it more approachable to newcomers!
Once we get to the point where the wiki page is relatively well written, I want to copy some of the content over to webmention.net, and give it a facelift. I'm always hesitant to share in-progress mockups, but hopefully doing so will spur some discussion. I'm thinking something along the lines of the mockup below, but maybe with a less stock-photo-y image, and some nicer typography.
Doing incremental improvements to the wiki page rather than jumping into a whole new design will ensure that we are focusing on getting the copy right. So please won't you help me continue to improve the wiki! 😊
-
@johnonolan @stefanbc https://withknown.com has built-in support, and http://micro.blog likely will as well. Lots of other small sites too
-
John O'Nolan
https://john.onolan.org
•
Feb 24
super open to this idea - I just have no idea what it would look like.@johnonolan @stefanbc @teabass I have a pretty good idea! https://www.w3.org/TR/webmention/ All the comments on my site are received via Webmention! -
Day 41: Easier Posting to IndieNews #100DaysOfIndieWeb
Following up on yesterday's update of adding a Webmention form on IndieNews' Webmention endpoint, today I finished building out the UI for submitting to IndieNews from a browser.
Now the "Submit" link includes a form where you can paste in your post's URL, in case your website doesn't send Webmentions automatically.
If you use this form to send the Webmention, then the response will be an HTML page instead of a JSON response. If the submission is successful, then it will actually return a 302 redirect to the IndieNews permalink of the post! This is a slight deviation from the Webmention spec, but it's fine because we don't really care if the browser is a spec-compliant Webmention client.
Also thanks to Chris Aldrich for the suggestion of using a dropdown for the target URL selection on the generic Webmention form.
This is the form you see when you visit the Webmention endpoint, which is not specific to the language you're on.
-
My reply to Micro.blog Project Surges Past $65K on Kickstarter, Gains Backing from DreamHost (boffosocko.com)"Webmention works much like @mention on Twitter, Medium, Facebook, and others, but is platform independent, which means you can use it to ping any website on the internet that supports it. Imagine if you could reply to someone on Twitter from your WordPress site? Or if you could use Facebook to reply to a post on Medium?"
-
Day 38: New Sneaky Redirect Test for webmention.rocks #100DaysOfIndieWeb
This was a tricky one, spawned from when sebsel failed to discover the Webmention endpoint for one of Zegnat's posts. In that case, the Webmention endpoint was a relative URL and sebsel was sending a Webmention to a URL that was also an HTTP redirect.
The new test, webmention.rocks #23, instructs you to send a Webmention to a URL that is a redirect, and that page advertises a relative URL endpoint. You'll need to make sure that the URL you pass to your relative URL resolver is the final URL after following the redirect, rather than the one you start with.
So give it a shot! Test if your relative URL resolution code works properly!
-
Day 34: New test for webmention.rocks #100DaysOfIndieWeb
Thanks to @Zegnat and @sebsel for finding some new new edges case in Webmention discovery that deserve new tests!
The new test, #22, advertises its Webmention endpoint with a URL that is relative to the page (e.g.
<link rel="webmention" href="22/webmention">). The existing relative URL tests were absolute paths (e.g.<link rel="webmention" href="/test/22/webmention">).
If you already handle relative URL resolution with a library then chances are you will pass this test without any new code.
-
I'm pretty pleased with the timestamps of both of these posts. One year to the minute!
https://aaronparecki.com/2016/01/12/14/webmention
https://aaronparecki.com/2017/01/12/13/webmention-rec -
We did it! Webmention is now a @W3C recommendation! Congrats @SocialWebWG and @IndieWebCamp! https://www.w3.org/TR/2017/REC-webmention-20170112/ https://twitter.com/w3c/status/819624363645353985
