@chrisburnell/eleventy-cache-webmentions 1.1.2 → 1.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +220 -7
- package/eleventy-cache-webmentions.js +1 -1
- package/package.json +15 -11
- package/.prettierrc +0 -4
package/README.md
CHANGED
|
@@ -1,19 +1,232 @@
|
|
|
1
1
|
# eleventy-cache-webmentions
|
|
2
2
|
|
|
3
|
-
> Cache webmentions using eleventy-fetch and make them available to use in collections, templates, pages, etc.
|
|
3
|
+
> Cache webmentions using eleventy-fetch and make them available to use in collections, templates, pages, etc. in Eleventy.
|
|
4
|
+
|
|
5
|
+
## Quick Guide
|
|
6
|
+
|
|
7
|
+
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/).
|
|
4
8
|
|
|
5
9
|
## Installation
|
|
6
10
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
11
|
+
- **With npm:** `npm install @chrisburnell/eleventy-cache-webmentions`
|
|
12
|
+
- **Direct download:** [https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.zip](https://github.com/chrisburnell/eleventy-cache-webmentions/archive/master.zip)
|
|
13
|
+
|
|
14
|
+
Once installed there are **two** more **required** set-up steps:
|
|
15
|
+
|
|
16
|
+
### Add it to your config
|
|
17
|
+
|
|
18
|
+
Inside your Eleventy config file (typically `.eleventy.js`), use `addPlugin`:
|
|
19
|
+
|
|
20
|
+
```javascript
|
|
21
|
+
const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
|
|
22
|
+
|
|
23
|
+
module.exports = function (eleventyConfig) {
|
|
24
|
+
eleventyConfig.addPlugin(pluginWebmentions, {
|
|
25
|
+
// these 3 fields are all required!
|
|
26
|
+
domain: "https://example.com",
|
|
27
|
+
feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
|
|
28
|
+
key: "children",
|
|
29
|
+
})
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Options
|
|
34
|
+
|
|
35
|
+
Advanced control over how the Webmentions are cached and processed is done by passing `options` into the plugin when using `addPlugin`:
|
|
36
|
+
|
|
37
|
+
```javascript
|
|
38
|
+
const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
|
|
39
|
+
|
|
40
|
+
module.exports = function (eleventyConfig) {
|
|
41
|
+
eleventyConfig.addPlugin(pluginWebmentions, {
|
|
42
|
+
// domain: required or the plugin will not function
|
|
43
|
+
// this is the website that you want to pull in Webmentions for
|
|
44
|
+
domain: "https://example.com",
|
|
45
|
+
// feed: required or the plugin will not function
|
|
46
|
+
// defines the URL of your Webmention server where a feed of Webmentions for your domain can be found
|
|
47
|
+
feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
|
|
48
|
+
// key: required or the plugin will not function
|
|
49
|
+
// dictates the key inside the feed where the array of Webmentions is located
|
|
50
|
+
key: "children",
|
|
51
|
+
// directory: ".cache" by default
|
|
52
|
+
// see https://www.11ty.dev/docs/plugins/cache/#cache-directory for more info
|
|
53
|
+
directory: ".cache",
|
|
54
|
+
// duration: "1d" by default
|
|
55
|
+
// see https://www.11ty.dev/docs/plugins/cache/#change-the-cache-duration for more info
|
|
56
|
+
duration: "1d",
|
|
57
|
+
// uniquekey: "webmentions" by default
|
|
58
|
+
// dictates the name sent to eleventy-fetch to name the file
|
|
59
|
+
uniqueKey: "webmentions",
|
|
60
|
+
// allowedHTML: Object by default
|
|
61
|
+
// see https://www.npmjs.com/package/sanitize-html for more info
|
|
62
|
+
allowedHTML: {
|
|
63
|
+
allowedTags: ["b", "i", "em", "strong", "a"],
|
|
64
|
+
allowedAttributes: {
|
|
65
|
+
a: ["href"],
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
// allowlist: [] by default
|
|
69
|
+
// array of root URLs from which webmentions are wanted exclusively
|
|
70
|
+
allowlist: [],
|
|
71
|
+
// blocklist: [] by default
|
|
72
|
+
// array of root URLs from which webmentions are not wanted
|
|
73
|
+
// exclusively
|
|
74
|
+
blocklist: [],
|
|
75
|
+
// urlReplacements: {} by default
|
|
76
|
+
// object of key:value pairs containing from:to URL replacements
|
|
77
|
+
urlReplacements: {},
|
|
78
|
+
// maximumHtmlLength: 2000 by default
|
|
79
|
+
// number of characters in the HTML content at which a different
|
|
80
|
+
// message is shown instead of the content
|
|
81
|
+
maximumHtmlLength: 2000,
|
|
82
|
+
// maximumHtmlText: "mentioned this in" by default
|
|
83
|
+
// message shown when maximumHtmlLength is reached
|
|
84
|
+
maximumHtmlText: "mentioned this in",
|
|
85
|
+
})
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## JavaScript Usage
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
```javascript
|
|
94
|
+
const Webmentions = require("@chrisburnell/eleventy-cache-webmentions")(null, {
|
|
95
|
+
domain: "https://example.com",
|
|
96
|
+
feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
|
|
97
|
+
key: "children",
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
const webmentionsByUrl = await Webmentions()
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
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/):
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
const Webmentions = require("@chrisburnell/eleventy-cache-webmentions")(null, {
|
|
107
|
+
domain: "https://example.com",
|
|
108
|
+
feed: "https://webmentions.example.com?token=S3cr3tT0k3n",
|
|
109
|
+
key: "children",
|
|
110
|
+
})
|
|
111
|
+
|
|
112
|
+
module.exports = async () => {
|
|
113
|
+
const webmentionsByUrl = await Webmentions()
|
|
114
|
+
|
|
115
|
+
return {
|
|
116
|
+
eleventyComputed: {
|
|
117
|
+
webmentions: (data) => {
|
|
118
|
+
const webmentionsForUrl = webmentionsByUrl["https://example.com" + data.page.url] || []
|
|
119
|
+
|
|
120
|
+
if (webmentionsForUrl.length) {
|
|
121
|
+
return webmentionsForUrl.sort((a, b) => {
|
|
122
|
+
return (b.data.published || b.verified_date) - (a.data.published || a.verified_date)
|
|
123
|
+
})
|
|
124
|
+
}
|
|
125
|
+
return []
|
|
126
|
+
},
|
|
127
|
+
},
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
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:
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
module.exports = (eleventyConfig) => {
|
|
136
|
+
eleventyConfig.addCollection("popular", (collection) => {
|
|
137
|
+
return collection.sort((a, b) => {
|
|
138
|
+
return b.data.webmentions.length - a.data.webmentions.length
|
|
139
|
+
})
|
|
140
|
+
})
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Liquid/Nunjucks Usage
|
|
145
|
+
|
|
146
|
+
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.
|
|
147
|
+
|
|
148
|
+
```twig
|
|
149
|
+
{% raw %}{% set responses = webmentions %}{% endraw %}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**OR**
|
|
153
|
+
|
|
154
|
+
```twig
|
|
155
|
+
{% raw %}{% set responses = page.url | getWebmentions %}{% endraw %}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
You can get back only specific [response post types](https://indieweb.org/responses#Response_Post_Types) by passing a second argument:
|
|
159
|
+
|
|
160
|
+
```twig
|
|
161
|
+
{% raw %}{% set reactions = page.url | getWebmentions(['like-of', 'repost-of', 'bookmark-of']) %}
|
|
162
|
+
{% set replies = page.url | getWebmentions(['mention-of', 'in-reply-to']) %}{% endraw %}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
And, if you need it, the entire Object of sorted Webmentions is available too:
|
|
166
|
+
|
|
167
|
+
```twig
|
|
168
|
+
{% raw %}{% set count = 0 %}
|
|
169
|
+
{% for url, array in webmentions %}
|
|
170
|
+
{% set count = array.length + count %}
|
|
171
|
+
{% endfor %}
|
|
172
|
+
<p>This site has received {{ count }} Webmentions!</p>{% endraw %}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
<h2 id="webmention-io">Webmention.io</h2>
|
|
176
|
+
|
|
177
|
+
[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/).
|
|
178
|
+
|
|
179
|
+
### Add your token
|
|
180
|
+
|
|
181
|
+
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:
|
|
182
|
+
|
|
183
|
+
```text
|
|
184
|
+
WEBMENTION_IO_TOKEN=njJql0lKXnotreal4x3Wmd
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Set your feed and key config options
|
|
188
|
+
|
|
189
|
+
```javascript
|
|
190
|
+
const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
|
|
191
|
+
|
|
192
|
+
module.exports = function (eleventyConfig) {
|
|
193
|
+
eleventyConfig.addPlugin(pluginWebmentions, {
|
|
194
|
+
domain: "https://example.com",
|
|
195
|
+
feed: `https://webmention.io/api/mentions.jf2?domain=example.com&per-page=9001&token=${process.env.WEBMENTION_IO_TOKEN}`,
|
|
196
|
+
key: "children",
|
|
197
|
+
})
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## go-jamming
|
|
202
|
+
|
|
203
|
+
[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).
|
|
204
|
+
|
|
205
|
+
### Add your token
|
|
206
|
+
|
|
207
|
+
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:
|
|
208
|
+
|
|
209
|
+
```text
|
|
210
|
+
GO_JAMMING_TOKEN=njJql0lKXnotreal4x3Wmd
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Set your feed and key config options
|
|
9
214
|
|
|
10
|
-
|
|
215
|
+
```javascript
|
|
216
|
+
const pluginWebmentions = require("@chrisburnell/eleventy-cache-webmentions")
|
|
11
217
|
|
|
12
|
-
|
|
218
|
+
module.exports = function (eleventyConfig) {
|
|
219
|
+
eleventyConfig.addPlugin(pluginWebmentions, {
|
|
220
|
+
domain: "https://example.com",
|
|
221
|
+
feed: `https://jam.example.com/webmention/example.com/${process.env.GO_JAMMING_TOKEN}`,
|
|
222
|
+
key: "json",
|
|
223
|
+
})
|
|
224
|
+
}
|
|
225
|
+
```
|
|
13
226
|
|
|
14
|
-
##
|
|
227
|
+
## Contributing
|
|
15
228
|
|
|
16
|
-
|
|
229
|
+
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.
|
|
17
230
|
|
|
18
231
|
## License
|
|
19
232
|
|
|
@@ -128,7 +128,7 @@ const fetchWebmentions = async (options) => {
|
|
|
128
128
|
}
|
|
129
129
|
|
|
130
130
|
const filteredWebmentions = async (options) => {
|
|
131
|
-
|
|
131
|
+
let rawWebmentions = await fetchWebmentions(options)
|
|
132
132
|
let webmentions = {}
|
|
133
133
|
|
|
134
134
|
// Process the blocklist, if it has any entries
|
package/package.json
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@chrisburnell/eleventy-cache-webmentions",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.4",
|
|
4
4
|
"description": "Fetch and cache webmentions using eleventy-fetch.",
|
|
5
|
-
"main": "eleventy-cache-webmentions.js",
|
|
6
5
|
"author": "Chris Burnell <me@chrisburnell.com>",
|
|
7
6
|
"license": "MIT",
|
|
8
7
|
"repository": {
|
|
@@ -12,9 +11,16 @@
|
|
|
12
11
|
"bugs": {
|
|
13
12
|
"url": "https://github.com/chrisburnell/eleventy-cache-webmentions/issues"
|
|
14
13
|
},
|
|
15
|
-
"
|
|
16
|
-
|
|
17
|
-
"
|
|
14
|
+
"keywords": [
|
|
15
|
+
"eleventy",
|
|
16
|
+
"eleventy-plugin",
|
|
17
|
+
"indieweb",
|
|
18
|
+
"javascript",
|
|
19
|
+
"js",
|
|
20
|
+
"webmention"
|
|
21
|
+
],
|
|
22
|
+
"devDependencies": {
|
|
23
|
+
"eslint": "^8.7.0"
|
|
18
24
|
},
|
|
19
25
|
"dependencies": {
|
|
20
26
|
"@11ty/eleventy-fetch": "^3.0.0",
|
|
@@ -22,10 +28,8 @@
|
|
|
22
28
|
"node-fetch": "^2.6.5",
|
|
23
29
|
"sanitize-html": "^2.7.1"
|
|
24
30
|
},
|
|
25
|
-
"
|
|
26
|
-
|
|
27
|
-
"eleventy-
|
|
28
|
-
|
|
29
|
-
"webmention"
|
|
30
|
-
]
|
|
31
|
+
"main": "eleventy-cache-webmentions.js",
|
|
32
|
+
"scripts": {
|
|
33
|
+
"lint": "eslint eleventy-cache-webmentions.js"
|
|
34
|
+
}
|
|
31
35
|
}
|
package/.prettierrc
DELETED