eleventy-cache-webmentions v0.1.10

Cache webmentions using eleventy-cache-assets and make them available to use in collections, templates, pages, etc.
There are nine star-gazers on GitHub and it was downloaded 260 times in the last month on npm.

Installation

Available on npm:

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

You can also just 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, {
domain: "https://example.com" // this is required!
})
}

Add your Webmention.io API Key

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:

WEBMENTION_IO_TOKEN=njJql0lKXnotreal4x3Wmd

Usage

Options

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: required or the plugin will not function
domain: "https://example.com",
// directory: ".cache" by default
// see https://www.11ty.dev/docs/plugins/cache/#cache-directory for more info
directory: ".cache",
// duration: "1d" by default
// see https://www.11ty.dev/docs/plugins/cache/#change-the-cache-duration for more info
duration: "1d",
// key: "webmentions" by default
// dictates the name sent to eleventy-cache-assets to name the file
key: "webmentions",
// allowedHTML: Object by default
// see https://www.npmjs.com/package/sanitize-html for more info
allowedHTML: {
allowedTags: ["b", "i", "em", "strong", "a"],
allowedAttributes: {
a: ["href"],
},
},
// urlReplacements: {} by default
// object of key:value pairs containing from:to URL replacements
urlReplacements: {},
// maximumHtmlLength: 2000 by default
// number of characters in the HTML content at which a different
// message is shown instead of the content
maximumHtmlLength: 2000,
// maximumHtmlText: "mentioned this in" by default
// message shown when maximumHtmlLength is reached
maximumHtmlText: "mentioned this in",
})
}

Accessing Webmentions with JavaScript

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" })

const webmentionsByUrl = await Webmentions()

You can now use this Object in a number of useful ways, not limited to things like creating a collection of posts ordered by number of webmentions:

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

const absoluteURL = (url, domain) => {
try {
return new URL(url, domain).toString()
} catch (e) {
console.log(`Trying to convert ${url} to be an absolute url with base ${domain} and failed.`)
return url
}
}

module.exports = (eleventyConfig) => {
eleventyConfig.addCollection("popular", async (collection) => {
const webmentionsByUrl = await Webmentions()
return await collection
.getFilteredByTag("post")
.filter((item) => {
// unfortunately necessary in order to match the key
const url = absoluteURL(item.url, "https://example.com")

if (!url) {
return false
}

return webmentionsByUrl[url]
})
.sort((a, b) => {
// unfortunately necessary in order to match the key
const aUrl = absoluteURL(a.url, "https://example.com")
const bUrl = absoluteURL(b.url, "https://example.com")
const aWebmentions = webmentionsByUrl[aUrl]
const bWebmentions = webmentionsByUrl[bUrl]

return bWebmentions.length - aWebmentions.length
})
})
}

Accessing Webmentions with Liquid/Nunjucks

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 = 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 webmentions %}
{% set count = array.length + count %}
{% endfor %}
<p>This site has received {{ count }} WebMentions!</p>

Next steps

  • It is currently hard-coded to utilise Webmention.io, but I'm not sure how to make this plugin agnostic of that. I need to do more research into what, if any, standard API parameters and output might be: ideally close to what I’m working with now.

23 Responses

  1. Avatar for hankchizljaw Andy Bell
  2. Avatar for schofeld Jonathan Schofield
  3. Avatar for hankchizljaw Andy Bell
  4. Avatar for schofeld Jonathan Schofield
  5. Avatar for theAdhocracy theAdhocracy
  6. Avatar for bnijenhuis Bernard Nijenhuis
  7. Avatar for thesapper Anthony Sapp
  8. Avatar for hexagoncircle Ryan Mulligan
  9. Avatar for superterrific DanaByerly.html
  10. Avatar for eleven_ty Eleventy (1.0.0-beta.8)
  11. Avatar for eleven_ty Eleventy (1.0.0-beta.8)
  12. Avatar for danleatherman dan leatherman
  13. Avatar for TerribleMia Mia, Keeper of All Gates
  14. Avatar for ginez_17 Ginestra Ferraro
  15. Avatar for pgrucza Peter Grucza
  16. Avatar for xkons64 Kons Ti
  17. Avatar for CSSInRealLife CSS {IRL}
  18. Avatar for Eduardo__Uribe Eduardo Uribe
  19. Avatar for papplegate Paul Applegate
  20. Avatar for binyamingreen Binyamin Green
  21. Avatar for binyamingreen Binyamin Green
Replies:
  1. Avatar for dletorey
    The awesome @iamchrisburnell has written a node package to cache #webmentions in @11ty so only the new webmentions are fetched each time and not all of them. #indieWeb chrisburnell.com/eleventy-cache…
  2. Avatar for chrisburnell.com
    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.