https://github.com/declanbyrd/eleventy-plugin-mastoarchive
Eleventy plugin to expose your Mastodon posts as a global data object.
https://github.com/declanbyrd/eleventy-plugin-mastoarchive
11ty 11ty-plugin eleventy eleventy-plugin mastodon
Last synced: 11 months ago
JSON representation
Eleventy plugin to expose your Mastodon posts as a global data object.
- Host: GitHub
- URL: https://github.com/declanbyrd/eleventy-plugin-mastoarchive
- Owner: declanbyrd
- Created: 2023-02-23T20:22:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-06T20:05:21.000Z (about 2 years ago)
- Last Synced: 2025-08-17T00:39:14.115Z (11 months ago)
- Topics: 11ty, 11ty-plugin, eleventy, eleventy-plugin, mastodon
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/eleventy-plugin-mastoarchive
- Size: 128 KB
- Stars: 12
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# eleventy-plugin-mastoarchive
> Fetch your own public posts from Mastodon so you can display them on your personal website.
## Getting Started
First install the plugin in your project:
```shell
npm i eleventy-plugin-mastoarchive
```
Then include it in your Eleventy project file
```js
const mastoArchive = require('eleventy-plugin-mastoarchive');
module.exports = (eleventyConfig) => {
eleventyConfig.addPlugin(mastoArchive, {
host: MASTODON_SERVER,
userId: MASTODON_USER_ID,
removeSyndicates: ['example.com'],
});
```
This will expose a global data object called `mastodon` which you can use in your Eleventy project.
On the first run, the plugin will fetch _all_ your public posts and then cache them to the location specified in `cacheLocation`. Each time posts are fetched after, only the posts made after the last cached post will be fetched.
If you used versions < 0.2.0 you will need to clear your site's cache to get all your posts and not the most recent 40.
## Getting your Mastodon User ID
I was able to retrieve my Mastodon user ID by monitoring the network requests made by the Mastodon server I belong to. On a device that is able to open developer tools, the steps I took were to:
- With the developer tools open and the Network traffic visible, enter your username in the search box and trigger the network request by pressing enter on your keyboard.
- Find the request that looks like `https://{mastodon_server}/api/v2/search?q=@{your_mastodon_username}` and open the response for that request. The response object should look like the one below.
- Your account should be the first one that appears under `accounts`. The id of that account is your Mastodon user ID.
```json
{
"accounts":[
{
"id": {your user ID},
"username": {your Mastodon username},
...
}
],
"statuses":[],
"hashtags":[]
}
```
## Config Options
| Option | Type | Default |
| ---------------- | -------- | ---------------------- |
| host | string | |
| userId | string | |
| removeSyndicates | string[] | [] |
| cacheLocation | string | ".cache/mastodon.json" |
| isProduction | boolean | true |
The `host` and `userId` are required for the plugin to work. The plugin will error if these are not provided.
## mastodon global data object
The `mastodon` object has the following properties:
| Property | Description |
| ----------- | ------------------------------------------------------------- |
| lastFetched | an ISO string indicating the last time the posts were fetched |
| posts | an array of posts |
### Mastodon posts
Each Mastodon post has the following properties:
| Property | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| date | The timestamp of the published post. |
| id | The internal ID of the post on the Mastodon server. |
| content | The HTML of the post as it is displayed in the Mastodon UI. |
| source_url | The original URL of the post. |
| site | Hard coded to "Mastodon". |
| media | An object if a single image or no image is attached to the post, or an array if multiple images are attached to the post. |
| emoji | An array of custom emojis that were used in the post. |
### Media objects
If the post contains a one or more images, the media property on the post will contain the following data:
| Property | Description |
| -------- | -------------------------------------------- |
| image | The URL of the image on the Mastodon server. |
| alt | The ALT text of the image. |
| width | The width of the image in pixels. |
| height | The height of the image in pixels. |
| aspect | The aspect ratio of the image. |
### Custom emoji
If your post contains custom emoji, the emoji property will contain the following data:
| Property | Description |
| --------- | ------------------------------------------------------------ |
| shortcode | The shortcode for the emoji. In the format `::`. |
| url | The static URL of the image on the Mastodon server. |