eleventy-plugin-embed-mastodon

This Eleventy plugin automatically embeds Mastodon posts from URLs in markdown files. It’s part of the eleventy-plugin-embed-everything project.

Install in Eleventy

In your Eleventy project, install the plugin through npm:

$ npm i eleventy-plugin-embed-mastodon

Then add it to your Eleventy config file (usually .eleventy.js):

const embedMastodon = require("eleventy-plugin-embed-mastodon");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(embedMastodon, {
		// Required setting:
		server: "your-mastodon-instance-hostname.net",
	});
};

Due to Mastodon’s decentralized nature, the plugin requires you to configure a server in order to work. This value should be the hostname of the Mastodon instance you log into. Some common examples are mastodon.social, pixelfed.social, or social.vivaldi.net, but there are thousands of Mastodon servers online.

For the value of server, only include the domain's hostname. Don't include the protocol (https:// or http://), a trailing slash, or any other part of your Mastodon instance's URL.

Usage

To embed a Mastodon post into any markdown page, paste its URL into a new line. The URL should be the only thing on that line.

The plugin will recognize statuses posted on your home Mastodon instance, as well as posts federated to your instance from other Mastodon servers.

Markdown file example:

...

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.

https://social.vivaldi.net/@[email protected]/113198584572922516

Maecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.

...

Result:

Settings

You can configure the plugin to change its behavior by passing an options object to the addPlugin function:

eleventyConfig.addPlugin(embedMastodon, {
  // just an example, see default values below:
  embedClass: 'custom-classname'
});

Plugin default options

The plugin’s default settings reside in lib/defaults.js. All of these values can be customized with an options object passed to the plugin.

Option | Type | Default | Notes ---|---|---|--- server Required | String | undefined | Hostname of the Mastodon server you log into to view your timeline. The plugin will recognize Mastodon URLs based on this value, and query this server for required information about federated posts from other Mastodon instances. cacheDuration | String | 60m | How long to cache Mastodon API data. Use the Eleventy Fetch syntax to set the duration. embedClass | String | "eleventy-plugin-embed-mastodon" | CSS class applied to the container <div> that wraps the embedded video.

Notes and caveats

• 📞 Due to Mastodon's distributed architecture, this plugin must make up to two network requests to retrieve the relevant embed data. Be aware that using this plugin will cause network requests during Eleventy’s build process. If the plugin experiences any network failure (such as if you're not connected to the internet), then it simply won’t complete the embed and the URL will be rendered as plain text.
• This plugin is deliberately designed only to embed when the URL is on its own line, and not inline with other text.
• To do this, it uses a regular expression to recognize URLs for your selected Mastodon instance, wrapped in an HTML <p> tag. If your Markdown parser produces any other output, it won’t be recognized.
• I’ve tried to accommodate common URL variants, but there are conceivably valid URLs that wouldn’t get recognized. Please file an issue if you run into an edge case!
• This plugin uses transforms, so it alters Eleventy’s HTML output as it’s generated. It doesn’t alter the source markdown.