tidy up README; lint JS; bump version

.editorconfig

@@ -8,9 +8,7 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{json,toml,yaml,yml}]
-indent_style = space
-indent_size = 2
-
 [*.md]
+indent_style = space
+indent_size = 4
 trim_trailing_whitespace = false

.eslintrc.json

@@ -0,0 +1,14 @@
+{
+ "env": {
+ "browser": true,
+ "commonjs": true,
+ "es2021": true
+ },
+ "extends": "eslint:recommended",
+ "parserOptions": {
+ "ecmaVersion": 12,
+ "sourceType": "module"
+ },
+ "rules": {
+ }
+}

.npmignore

@@ -1,3 +1,4 @@
 .github
 .vscode
 .editorconfig
+.prettier

.vscode/settings.json

@@ -1,7 +1,5 @@
 {
  "workbench.colorCustomizations": {
- // "activityBar.background" : "#507791",
- // "activityBar.foreground" : "#f9f9f9",
  "titleBar.activeBackground" : "#4f758e",
  "titleBar.activeForeground" : "#f9f9f9",
  "titleBar.inactiveBackground" : "#44657A",

README.md

@@ -1,19 +1,232 @@
 # eleventy-cache-webmentions
 
-> Cache webmentions using eleventy-fetch and make them available to use in collections, templates, pages, etc.
+> Cache webmentions using eleventy-fetch and make them available to use in collections, templates, pages, etc. in Eleventy.
+
+## 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](https://chrisburnell.com/article/webmention-eleventy-setup/).
 
 ## Installation
 
-- **With npm:** `npm install @chrisburnell/eleventy-cache-webmentions`
-- **Direct download:** [https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.zip](https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.zip)
+- **With npm:** `npm install @chrisburnell/eleventy-cache-webmentions`
+- **Direct download:** [https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.zip](https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.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`:
+
+```javascript
+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
+
+Advanced control over how the Webmentions are cached and processed is done by passing `options` into the plugin when using `addPlugin`:
+
+```javascript
+const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
+
+module.exports = function (eleventyConfig) {
+ eleventyConfig.addPlugin(pluginWebmentions, {
+ // domain: required or the plugin will not function
+ // this is the website that you want to pull in Webmentions for
+ domain: "https://example.com",
+ // feed: required or the plugin will not function
+ // defines the URL of your Webmention server where a feed of Webmentions for your domain can be found
+ feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
+ // key: required or the plugin will not function
+ // dictates the key inside the feed where the array of Webmentions is located
+ key: "children",
+ // 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",
+ // uniquekey: "webmentions" by default
+ // dictates the name sent to eleventy-fetch to name the file
+ uniqueKey: "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"],
+ },
+ },
+ // allowlist: [] by default
+ // array of root URLs from which webmentions are wanted exclusively
+ allowlist: [],
+ // blocklist: [] by default
+ // array of root URLs from which webmentions are not wanted
+ // exclusively
+ blocklist: [],
+ // 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",
+ })
+}
+```
+
+## 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.
+
+```javascript
+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](https://www.11ty.dev/docs/data-cascade/), we can attach Webmentions to each page by using [Directory Specific Data Files](https://www.11ty.dev/docs/data-template-dir/):
+
+```javascript
+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:
+
+```javascript
+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.
+
+```twig
+{% raw %}{% set responses = webmentions %}{% endraw %}
+```
+
+**OR**
+
+```twig
+{% raw %}{% set responses = page.url | getWebmentions %}{% endraw %}
+```
+
+You can get back only specific [response post types](https://indieweb.org/responses#Response_Post_Types) by passing a second argument:
+
+```twig
+{% raw %}{% set reactions = page.url | getWebmentions(['like-of', 'repost-of', 'bookmark-of']) %}
+{% set replies = page.url | getWebmentions(['mention-of', 'in-reply-to']) %}{% endraw %}
+```
+
+And, if you need it, the entire Object of sorted Webmentions is available too:
+
+```twig
+{% raw %}{% set count = 0 %}
+{% for url, array in webmentions %}
+ {% set count = array.length + count %}
+{% endfor %}
+<p>This site has received {{ count }} Webmentions!</p>{% endraw %}
+```
+
+<h2 id="webmention-io">Webmention.io</h2>
+
+[Webmention.io](https://webmention.io) is a in-place Webmention receiver solution that you can use by authenticating yourself via [IndieAuth](https://indieauth.com/) (or host it yourself), and, like so much other publically-available IndieWeb software, is built and hosted by [Aaron Parecki](https://aaronparecki.com/).
+
+### Add your token
+
+Get set up on [Webmention.io](https://webmention.io) and add your **API Key** (found on your [settings page](https://webmention.io/settings)) to your project as an environment variable, i.e. in a `.env` file in the root of your project:
+
+```text
+WEBMENTION_IO_TOKEN=njJql0lKXnotreal4x3Wmd
+```
+
+### Set your feed and key config options
+
+```javascript
+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](https://git.brainbaking.com/wgroeneveld/go-jamming) is a self-hosted Webmention sender and receiver, built in Go by [Wouter Groeneveld](https://brainbaking.com) and available with more information on his [personal git instance](https://git.brainbaking.com/wgroeneveld/go-jamming).
+
+### 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:
+
+```text
+GO_JAMMING_TOKEN=njJql0lKXnotreal4x3Wmd
+```
+
+### Set your feed and key config options
 
-## Documentation
+```javascript
+const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
 
-The full **eleventy-cache-webmentions** documentation can be found here: [chrisburnell.com/eleventy-cache-webmentions/](https://chrisburnell.com/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",
+ })
+}
+```
 
-## Authors
+## Contributing
 
-So far, it’s just myself, [Chris Burnell](https://chrisburnell.com), but I welcome collaborators with ideas to bring to the table!
+Contributions of all kinds are welcome! Please [submit an Issue on GitHub](https://github.com/chrisburnell/eleventy-cache-webmentions/issues) or [get in touch with me](https://chrisburnell.com/about/#contact) if you’d like to do so.
 
 ## License
 

eleventy-cache-webmentions.js

@@ -128,7 +128,7 @@ const fetchWebmentions = async (options) => {
 }
 
 const filteredWebmentions = async (options) => {
- const rawWebmentions = await fetchWebmentions(options)
+ let rawWebmentions = await fetchWebmentions(options)
  let webmentions = {}
 
  // Process the blocklist, if it has any entries

package.json

@@ -1,8 +1,7 @@
 {
  "name": "@chrisburnell/eleventy-cache-webmentions",
- "version": "1.1.2",
+ "version": "1.1.3",
  "description": "Fetch and cache webmentions using eleventy-fetch.",
- "main": "eleventy-cache-webmentions.js",
  "author": "Chris Burnell <me@chrisburnell.com>",
  "license": "MIT",
  "repository": {
@@ -12,20 +11,27 @@
  "bugs": {
  "url": "https://github.com/chrisburnell/eleventy-cache-webmentions/issues"
  },
- "homepage": "https://chrisburnell.com/eleventy-cache-webmentions/",
+ "keywords": [
+ "eleventy",
+ "eleventy-plugin",
+ "indieweb",
+ "javascript",
+ "js",
+ "webmention"
+ ],
  "engines": {
  "node": ">=10"
  },
+ "devDependencies": {
+ "eslint": "^8.7.0"
+ },
  "dependencies": {
  "@11ty/eleventy-fetch": "^3.0.0",
  "lodash": "^4.17.21",
  "node-fetch": "^2.6.5",
  "sanitize-html": "^2.7.1"
  },
- "keywords": [
- "eleventy",
- "eleventy-plugin",
- "indieweb",
- "webmention"
- ]
+ "scripts": {
+ "test": "eslint eleventy-cache-webmentions.js"
+ }
 }