eleventy-plugin-webmentions

A plugin for eleventy to fetch and filter webmentions from Webmention.io.

Install

Available on npm.

npm install --save-dev eleventy-plugin-webmentions

Usage

In your Eleventy config file (probably .eleventy.js), load the plugin module and use .addPlugin to add it to Eleventy with an options object that defines the domain and the Webmention.io token. Like this:

const Webmentions = require("eleventy-plugin-webmentions");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(Webmentions, {
    domain: "lukeb.co.uk",
    token: "ABC123XYZ987",
  });
};

REMEMBER: You’re only allowed one module.exports in your configuration file, so make sure you only copy the require and the .addPlugin lines above! (Including the configuration options)

The plugin then adds 2 global data objects. One is called webmentionsLastFetched and is a Date object with the date that the plugin last fetched webmentions, and the other is called webmentions and is an array of webmention objects that look similar to this:

{
  type: 'entry',
  author: {
    type: 'card',
    name: 'Zach Leatherman',
    photo: 'https://webmention.io/avatar/pbs.twimg.com/d9711a9ad30ae05a761e4a728883bcbdd852cbf7d41437925b0afc47a8589795.jpg',
    url: 'https://twitter.com/zachleat'
  },
  url: 'https://twitter.com/zachleat/status/1524800520208142337',
  published: '2022-05-12T17:15:48+00:00',
  'wm-received': '2022-05-13T00:05:16Z',
  'wm-id': 1397424,
  'wm-source': 'https://brid.gy/comment/twitter/CodeFoodPixels/1524795680966991874/1524800520208142337',
  'wm-target': 'https://lukeb.co.uk/blog/2022/01/17/pixelated-rounded-corners-with-css-clip-path/',
  content: {
    html: 'The step-by-step here was/is incredible detailed!\n' +
      '<a class="u-mention" href="http://lukeb.co.uk/"></a>\n' +
      '<a class="u-mention" href="https://twitter.com/CodeFoodPixels"></a>',
    text: 'The step-by-step here was/is incredible detailed!',
    value: 'The step-by-step here was/is incredible detailed! <a></a> <a></a>'
  },
  'in-reply-to': 'https://lukeb.co.uk/blog/2022/01/17/pixelated-rounded-corners-with-css-clip-path/',
  'wm-property': 'in-reply-to',
  'wm-private': false
}

It also adds 2 filters:

webmentionsForPage will return the webmentions for that page, in the structure defined by the mentionTypes option.
webmentionCountForPage will return the number of webmentions for a page, filtered by the types used in the mentionTypes option.

Here is an example of using the filters in nunjucks:

{# Get the webmentions for the current page #}
{%- set currentPostMentions = webmentions | webmentionsForPage -%}

{# Get the webmentions for a specific page #}
{%- set postMentions = webmentions | webmentionsForPage(post.url) -%}

{# Get the webmention count for the current page #}
{%- set currentPostMentionCount = webmentions | webmentionCountForPage -%}

{# Get the webmention count for a page #}
{%- set postMentionCount = webmentions | webmentionCountForPage(post.url) -%}

Configuration

Below are all the options that can be passed to the plugin:

Option	Type	Required?	Default	Description
`domain`	string	Required	`undefined`	The domain you wish to get the webmentions for.
`token`	string	Required	`undefined`	The webmention.io token (found at the bottom of [the webmention.io settings page](https://webmention.io/settings)).
`cacheDirectory`	string	Optional	`./_webmentioncache`	The directory for webmentions to be cached to.
`cacheTime`	integer	Optional	`3600`	The time in seconds for the cached webmentions to be considered "fresh".
`truncate`	boolean	Optional	`true`	Whether or not to truncate the webmentions
`maxContentLength`	integer	Optional	`280`	The length to truncate webmentions to if `truncate` is true
`truncationMarker`	string	Optional	`…`	The string to truncate the content with
`htmlContent`	boolean	Optional	`true`	Whether or not to return HTML content from the webmentions. If `false`, just text content will be returned.
`useCanonicalTwitterUrls`	boolean	Optional	`true`	Whether or not to convert Twitter URLs using tweetback-canonical
`pageAliases`	object	Optional	`{}`	An object keyed by page path, with the values either being a string of a page that is an alias of that page (e.g an old page that has been redirected) or an array of strings.
`mentionTypes`	object	Optional	{ likes: ["like-of"], reposts: ["repost-of"], comments: [ "mention-of", "in-reply-to" ] }	A single layer object with groupings and types that should be returned for that grouping. The object can have any keys you wish (doesn't have to be `likes`, `reposts` and `comments` like the default) but each value should be an array of webmention types.You can find a list of possible types here
`sanitizeOptions`	object	Optional	{ allowedTags: ["b", "i", "em", "strong", "a", "p"], allowedAttributes: { a: ["href"], }, }	A set of options passed to `sanitize-html`. You can find a full list of available options here You can find a full list of available options here
`sortFunction`	function	Optional	(a, b) => { new Date(a.published \|\| a["wm-received"]) - new Date(b.published \|\| b["wm-received"])	A function to use when sorting the webmentions. By default, the webmentions will be sorted in date ascending order, either by when they were published or when they were recieved.

Defaults

All of the defaults are exposed on the defaults property of the module, so they can be used in your config if necessary.

Here is an example of extending the sanitizeOptions object:

const Webmentions = require("eleventy-plugin-webmentions");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(Webmentions, {
    domain: "lukeb.co.uk",
    token: "ABC123XYZ987",
    sanitizeOptions: {
      ...Webmentions.defaults.sanitizeOptions,
      allowedTags: [
        ...Webmentions.defaults.sanitizeOptions.allowedTags,
        "iframe",
        "marquee",
      ],
      disallowedTagsMode: "escape",
    },
  });
};

Trying to add this to my site

I upgraded to the latest version of eleventy and went through the steps on Luke's post and the readme.

Trying to use the plugin's filters, I copied some of the code from Luke's site's post.njk template

On my local build I am getting these errors:

`TemplateWriterWriteError` was thrown
> (./src/_includes/layouts/post.njk)
  Error: filter not found: webmentionCountForPage

`Template render error` was thrown:
    Template render error: (./src/_includes/layouts/post.njk)
      Error: filter not found: webmentionCountForPage
        at Object._prettifyError (/.../nicksimsondotcom/node_modules/nunjucks/src/lib.js:36:11)
        at /.../nicksimsondotcom/node_modules/nunjucks/src/environment.js:563:19
        at Template.root [as rootRenderFunc] (eval at _compile (/.../nicksimsondotcom/node_modules/nunjucks/src/environment.js:633:18), <anonymous>:91:3)
        at Template.render (/.../nicksimsondotcom/node_modules/nunjucks/src/environment.js:552:10)
        at /.../nicksimsondotcom/node_modules/@11ty/eleventy/src/Engines/Nunjucks.js:236:14
        at new Promise (<anonymous>)
        at /.../nicksimsondotcom/node_modules/@11ty/eleventy/src/Engines/Nunjucks.js:235:14
        at TemplateLayout.render (/.../nicksimsondotcom/node_modules/@11ty/eleventy/src/TemplateLayout.js:152:31)
        at processTicksAndRejections (internal/process/task_queues.js:95:5)
        at async Template.renderPageEntry (/.../nicksimsondotcom/node_modules/@11ty/eleventy/src/Template.js:603:17)

Is there something I may be overlooking?

codefoodpixels / eleventy-plugin-webmentions Goto Github PK