Note: This is the Introduction to a five-part series about how you can set up webmentions in Web sites built by three different static site generators (SSGs): Eleventy, Hugo, and Gatsby. In the conclusion, you’ll find a bibliography of the best articles I found on the subject of this series. All of the articles link (even if only through tiny GitHub logos) to their authors’ code. They were invaluable to this effort, and I encourage you to take particular notice of them and their authors.
It’s an often-misattributed phrase: “Good artists copy; great artists steal.” Well, in the case of your faithful correspondent, here, it’s more a case of “Great coders code; mediocre coders borrow shamelessly.” But, if I didn’t, I couldn’t keep this site going, so shameless I shall continue to be.
A few months ago, I first learned of the IndieWeb movement and, more to the point, webmentions. In case you’re new to this stuff, too, the idea behind webmentions is that people should own their own Web content because it’s unwise to depend on third parties—even apparently financially healthy ones—to keep that content safe for the future. Having your own personal Web site is part of that idea, but having webmention functionality on that site is another major puzzle piece.
When I converted this site to an Eleventy-/webpack-based platform a few months back, I also began a tentative, gradual integration of webmentions into the site. As mentioned before, I leaned heavily (out of my usual necessity) on code and articles by others who’d mastered this on their own sites. That’s when I knew I’d be writing this post; but I’ll get to that in a moment.
A few weeks ago, I decided to launch public repositories of this site as it would be executed in its former static site generators (SSGs), Hugo and Gatsby. I hoped these would serve somewhat as a “Rosetta Stone” in that all three would result in the same final site, so people interested in switching from one SSG to another could say, “Ah, yeah, I see: in this one you use this code to get there, and in the other one you use that code. That makes sense.”
Although I said at the time that I’d be wary about keeping those repos up to date with this one for more than just additional posts as they came along—i.e., as opposed to making configuration changes—my challenge- and tinkering-loving brain wasn’t having any of that.
Accordingly, when I enhanced this site’s webmentions capabilities recently so that it now shows more kinds of webmentions, I couldn’t resist doing the same for the other two repos. And, this past Saturday, I was able to post the necessary changes to them.
This series is for sharing some of what I learned in the process. That’s especially true where the Hugo and Gatsby repos were concerned, because getting them up to speed, notably the Gatsby repo, required quite a bit more futzing as compared to doing it in the Eleventy repo. I therefore decided to use this series as a way of providing help for anyone else who might want to add webmentions to a Web site based on any of these three SSGs.
Does this series amount to the articles I wish I could’ve read before I started? No, but I do hope it will help you avoid some of the things that had me metaphorically beating my head against the computer screen for several nights in a row trying to find answers.
In particular, I found it really difficult to follow the logic in certain articles’ related code. I ended up “chasing” variables, constants, and statements from other files—and sourly muttering things like “Where’d that come from?” and “What’s that got to do with what’s supposed to be happening here?” and “Wait a minute; what happened to the step before this part?”
And no chase scenes involved, I hope.
Getting started: The very basics
It’s not within the scope of this series to give you extensive details about the general niceties of making your site compatible with webmentions in the first place. Fortunately, IndieWebify.Me not only is pretty much the canonical location for that, but also makes it easy.
To facilitate the capture of webmentions for my site, I chose to use a combination of two free, hosted services: webmention.io, which is an endpoint for receiving webmentions for Web pages registered with it; and Bridgy, which “watches” social media sites for responses to its registered users’ pages and sends the responses back to those pages as webmentions. Each service has pretty simple instructions for how to sign up with and start using it. In my case, I did the following for each repo:
Added the necessary microformats information to the site footer. This essentially acts like a “beacon” to other sites, “announcing” pages’ titles, descriptions, and more. The other sites can then “respond.”
Added to the site’s universal
<HEAD>section the appropriate
link rel="pingback"HTML. This enables webmention.io to collect webmentions and “pingbacks” for the site pages.
So that’s the generic webmention-ization process I followed, but keep in mind that all it does is start fetching your webmentions for you out on webmention.io. The nitty-gritty yet to come is when you subsequently fetch them from webmention.io and make them actually appear on your site. How you can do it varies from SSG to SSG, hence this series.
We’ll start with Eleventy in Part 2, move on to Hugo in Part 3, and get to Gatsby in Part 4. That’ll be followed in the conclusion, Part 5, with a wrap-up—and that previously referenced bibliography for the series.
I’d urge you to read them in order so as to get the whole picture, but I surely understand you may want to read about only the SSG you’re using. If so, maybe you could skim the other two and spend most of your time on the part that interests you most, but I still think it would be best to skim/read in order, if possible.
Incidentally, I freely acknowledge that this site hasn’t gone fully webmention-friendly. That would involve not only showing webmentions it receives but also facilitating the sending of them directly from the site itself. So far, I haven’t seen fit to go that route, although it (sort of) remains on my mental agenda. ↩︎