Webmention Setup for Eleventy

1. Account Creation Permalink ¶

Unless you already have your own Webmention receiver, sign up for one and add the secret key/token to your project. Below are two examples:

If you’re using Webmention.io, add your API Key (found on your settings page) to your project as an environment variable, i.e. in a .env file in the root of your project:

WEBMENTION_IO_TOKEN=njJql0lKXnotreal4x3Wmd

If you’re using go-jamming, once you’ve set up your server and defined your token, you’ll need add it to your project as an environment variable, i.e. in a .env file in the root of your project:

GO_JAMMING_TOKEN=njJql0lKXnotreal4x3Wmd

2. Installation Permalink ¶

Install the eleventy-cache-webmentions package from npm:

npm install @chrisburnell/eleventy-cache-webmentions --save-dev

3. Configuration Permalink ¶

Create a config file. You may wish to put this file in your Global Data Folder so you can access the data in Eleventy as well. However, the location and filename of your config file are up to you, as long as it’s somewhere in your project that you can access with JavaScript using require().

If you’re using Webmention.io:

const { defaults } = require("@chrisburnell/eleventy-cache-webmentions")()

// Load .env variables with dotenv
require("dotenv").config()

module.exports = Object.assign(defaults, {
	domain: "https://EXAMPLE.COM",
	feed: `https://webmention.io/api/mentions.json?domain=EXAMPLE.COM&token=${process.env.WEBMENTION_IO_TOKEN}&per-page=9001`,
	key: "links",
})

If you’re using go-jamming:

const { defaults } = require("@chrisburnell/eleventy-cache-webmentions")()

// Load .env variables with dotenv
require("dotenv").config()

module.exports = Object.assign(defaults, {
	domain: "https://EXAMPLE.COM",
	feed: `https://JAM.EXAMPLE.COM/webmention/EXAMPLE.COM/${process.env.GO_JAMMING_TOKEN}`,
	key: "json",
})

4. Integrate with Eleventy Permalink ¶

Add both to Eleventy by adding them to your Eleventy Config:

const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
const configWebmentions = require("../path_to_your_config/configWebmentions.js")

module.exports = function(eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebmentions, configWebmentions)
}

5. Attach Webmentions to Pages Permalink ¶

Add some Directory Specific Data Files wherever your pages and/or posts live. For example, if your pages all live in a pages/ folder, you would add the following code block to a pages.11tydata.js file inside pages/:

const { getWebmentions } = require("@chrisburnell/eleventy-cache-webmentions")()
const configWebmentions = require("../path_to_your_config/configWebmentions.js")

module.exports = {
	eleventyComputed: {
		webmentions: (data) => {
			return getWebmentions(configWebmentions, configWebmentions.domain + data.page.url)
		},
	}
}

6. Use Webmentions Permalink ¶

Webmentions are now attached to each page!

You can access them quite easily on a given page:

{% for webmention in webmentions %}
	<!-- Loop through all webmentions on a given page -->
	{{ webmention.author.name }} sent this page a {{ webmention.activity.type }}
{% endfor %}

And even when looping through something like a collection:

{% for item in collections.pages %}
	<!-- Loop through all items in a collection -->
	<h2>{{ item.data.title }}</h2>
	<p>This page has {{ item.data.webmentions.length }} webmention{{ 's' if item.data.webmentions.length == 2 }}</p>
{% endfor %}

How you want to filter the array of Webmentions attached to each page is up to you, but I recommend using the type value (activity.type in Webmention.io; type in go-jamming) to split Webmentions into groups categorised by type—this will make it easier to figure out which Webmentions are binary interactions (e.g. likes, reposts) and which have richer content you might want to display (e.g. mentions, replies).

And that's pretty much all there is to it! Let me know if you have any suggestions or issues, and feel free to contribute back to the Eleventy plugin that is the workhorse behind this implementation over on GitHub or just get in touch.