eleventy-cache-webmentions v1.2.2

Cache Webmentions using eleventy-fetch and make them available to use in collections, templates, pages, etc. in Eleventy.
There are 14 stargazers on GitHub and it was downloaded 327 times in the last month on npm.

Quick Guide

I wrote a quicker and simpler guide to getting this Eleventy plugin working that cuts out all the fluff and extra details. You can read about it here: Webmention Setup for Eleventy.

Installation

Available on npm:

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

You can also download it directly from GitHub: https://github.com/chrisburnell/eleventy-cache-webmentions/archive/main.zip

Once installed there are two more required set-up steps:

Add it to your config

Inside your Eleventy config file (typically .eleventy.js), use addPlugin:

const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(pluginWebmentions, {
        // these 3 fields are all required!
        domain: "https://example.com",
        feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
        key: "children"
    })
}

Options

option default value description version added
domain
required
The website you’re fetching Webmentions for. 0.0.1
feed
required
The URL of your Webmention server’s feed for your domain. 0.2.0
key
required
The key in the above feed whose value is an Array of Webmentions. 0.0.1
directory ".cache" See Eleventy Fetch’s Cache Directory for more information. 1.1.2
duration "1d" or 1 day See Eleventy Fetch’s Cache Duration for more information. 0.0.1
uniqueKey "webmentions" The name of the file generated by Eleventy Fetch. 0.1.9
allowedHTML See code example below See the sanitize-html package for more information. 0.0.1
allowlist [] An Array of root URLs from which Webmentions are kept. 1.1.0
blocklist [] An Array of root URLs from which Webmentions are discarded. 1.1.0
urlReplacements {} An Object of key-value string pairs containing from-to URL replacements on this domain. 0.0.3
maximumHtmlLength 2000 Maximum number of characters in a Webmention’s HTML content, beyond which point a different message is shown, referring to the original source. 0.0.1
maximumHtmlText "mentioned this in" The glue-y part of the message displayed when a Webmention content’s character count exceeds maximumHtmlLength. 0.1.0

Advanced control over how the Webmentions are cached and processed is done by passing options into the plugin when using addPlugin:

const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(pluginWebmentions, {
        domain: "https://example.com",
        feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
        key: "children",
        directory: ".cache",
        duration: "1d",
        uniqueKey: "webmentions",
        allowedHTML: {
            allowedTags: ["b", "i", "em", "strong", "a"],
            allowedAttributes: {
                a: ["href"],
            },
        },
        allowlist: [],
        blocklist: [],
        urlReplacements: {},
        maximumHtmlLength: 2000,
        maximumHtmlText: "mentioned this in",
    })
}

JavaScript Usage

Accessing the plugin in JavaScript in the way shown below will give you an Object containing your cached Webmentions organised in key:value pairs where the key is a URL on your domain and the value is an array of data for Webmentions sent to that URL.

const Webmentions = require("@chrisburnell/eleventy-cache-webmentions")(null, {
    domain: "https://example.com",
    feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
    key: "children"
})

const webmentionsByUrl = await Webmentions()

This can prove to be very useful when building out your pages. Using Eleventy’s Data Cascade, we can attach Webmentions to each page by using Directory Specific Data Files:

const Webmentions = require("@chrisburnell/eleventy-cache-webmentions")(null, {
    domain: "https://example.com",
    feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
    key: "children"
})

module.exports = async () => {
    const webmentionsByUrl = await Webmentions()

    return {
        eleventyComputed: {
            webmentions: (data) => {
                const webmentionsForUrl = webmentionsByUrl["https://example.com" + data.page.url] || []

                if (webmentionsForUrl.length) {
                    return webmentionsForUrl.sort((a, b) => {
                        return (b.data.published || b.verified_date) - (a.data.published || a.verified_date)
                    })
                }
                return []
            },
        },
    }
}

You can now use this data in a number of useful ways, not limited to things like creating a collection of pages ordered by number of Webmentions:

module.exports = (eleventyConfig) => {
    eleventyConfig.addCollection("popular", (collection) => {
        return collection
            .sort((a, b) => {
                return b.data.webmentions.length - a.data.webmentions.length
            })
    })
}

Liquid/Nunjucks Usage

Accessing the plugin in Liquid/Nunjucks by using a Filter and passing in a URL in the way shown below will give you an Array containing the cached Webmentions for the given URL.

{% set responses = webmentions %}

OR

{% set responses = page.url | getWebmentions %}

You can get back only specific response post types by passing a second argument:

{% set reactions = page.url | getWebmentions(['like-of', 'repost-of', 'bookmark-of']) %}
{% set replies = page.url | getWebmentions(['mention-of', 'in-reply-to']) %}

And, if you need it, the entire Object of sorted Webmentions is available too:

{% set count = 0 %}
{% for url, array in webmentionsAll %}
    {% set count = array.length + count %}
{% endfor %}
<p>This site has received {{ count }} Webmentions!</p>

Webmention.io

Webmention.io is a in-place Webmention receiver solution that you can use by authenticating yourself via IndieAuth (or host it yourself), and, like so much other publically-available IndieWeb software, is built and hosted by Aaron Parecki.

Add your token

Get set up on Webmention.io and 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

Set your feed and key config options

const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(pluginWebmentions, {
        domain: "https://example.com",
        feed: `https://webmention.io/api/mentions.jf2?domain=example.com&per-page=9001&token=${process.env.WEBMENTION_IO_TOKEN}`,
        key: "children"
    })
}

go-jamming

go-jamming is a self-hosted Webmention sender and receiver, built in Go by Wouter Groeneveld and available with more information on his personal git instance.

Add your token

Once you’ve set up your go-jamming server and you’ve 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

Set your feed and key config options

const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")

module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(pluginWebmentions, {
        domain: "https://example.com",
        feed: `https://jam.example.com/webmention/example.com/${process.env.GO_JAMMING_TOKEN}`,
        key: "json"
    })
}

39 Responses

  1. 14 Stargazers
  2. 17 Likes
  3. 2 Links
  4. 4 Reposts
  1. Chris Burnell

    Fixed a bug in eleventy-cache-webmentions from a silly assumption I made about determining a since value to get new webmentions when the cache exists.

  2. Chris Burnell

    Given a couple of assumptions about how the data is returned from the server, this change allows you to use different Webmention servers, hopefully lessening the inherent dependency on Webmention.io.

    This change does mean that there are now two more required fields that need to be passed to the plugin when invoking it in your .eleventy.js file with addPlugin():

    const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")

    module.exports = function(eleventyConfig) {
    eleventyConfig.addPlugin(pluginWebmentions, {
    // these 3 fields are all required!
    domain: "https://example.com",
    feed: "https://webmention.io/api/mentions.jf2?domain=example.com&token=${process.env.WEBMENTION_IO_TOKEN}&per-page=9001",
    key: "children"
    })
    }

    The above example, which I’m hoping is simple to update in existing configs, outlines how to use the plugin with Webmention.io.