{% tableofcontents %}

At their simplest, Eleventy plugins are a function passed to the addPlugin method. If you’re familiar with Eleventy configuration files, this will look and feel very similar!

{% set codeContent %} export default function (eleventyConfig) { eleventyConfig.addPlugin(function(eleventyConfig) { // I am a plugin! }); }; {% endset %} {% include "snippets/configDefinition.njk" %}

The plugin can be defined elsewhere in the same file:

{% set codeContent %} function myPlugin(eleventyConfig) { // I am a plugin! }

export default function (eleventyConfig) { eleventyConfig.addPlugin(myPlugin); }; {% endset %} {% include "snippets/configDefinition.njk" %}

Or in a different file:

{% set codeContent %} import myPlugin from "./_config/plugin.js";

export default function (eleventyConfig) { eleventyConfig.addPlugin(myPlugin); }; {% endset %} {% include "snippets/configDefinition.njk" %}

Or in an npm package:

{% set codeContent %} import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) { eleventyConfig.addPlugin(pluginRss); }; {% endset %} {% include "snippets/configDefinition.njk" %}

Plugins are async-friendly {% addedin "3.0.0-alpha.1" %} but you must await the addPlugin method.

{% set codeContent %} export default async function (eleventyConfig) { await eleventyConfig.addPlugin(async function(eleventyConfig) { // I am an asynchronous plugin! }); }; {% endset %} {% include "snippets/configDefinition.njk" %}

We use the npm command line tool (included with Node.js) to install plugins.

Looking for a plugin? Check out the official plugins or community-contributed plugins.

npm install @11ty/eleventy-plugin-rss --save

Your config file is probably named eleventy.config.js or .eleventy.js.

{% set codeContent %} import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) { eleventyConfig.addPlugin(pluginRss); }; {% endset %} {% include "snippets/configDefinition.njk" %}

Use an optional second argument to addPlugin to customize your plugin’s behavior. These options are specific to the plugin. Please consult the plugin’s documentation (e.g. the eleventy-plugin-syntaxhighlight README) to learn what options are available to you.

{% set codeContent %} import pluginSyntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";

export default function (eleventyConfig) { eleventyConfig.addPlugin(pluginSyntaxHighlight, { // only install the markdown highlighter templateFormats: ["md"],

	init: function ({ Prism }) {
		// Add your own custom language to Prism!
	},
});

}; {% endset %} {% include "snippets/configDefinition.njk" %}

Plugins (by default) execute in a second stage of configuration after the user’s configuration file has finished, in order to have access to the return object in the configuration callback.

You are unlikely to need this, but you can execute a plugin’s code immediately using the immediate option.

{% set codeContent %} export default function (eleventyConfig, pluginOptions) { console.log( "first" );

eleventyConfig.addPlugin(eleventyConfig => {
	console.log("fourth");
});

eleventyConfig.addPlugin(eleventyConfig => {
	console.log("second");
}, {
	immediate: true
});

console.log("third");

}; {% endset %} {% include "snippets/configDefinition.njk" %}

A plugin primarily provides a “configuration function.” This function is called when Eleventy is first initialized, and operates similarly to a user’s configuration function (the same eleventyConfig argument passed to the user’s eleventy.config.js file is passed here), in addition to any config passed by the user:

{% set codeContent %} export default function (eleventyConfig, pluginOptions) { // Your plugin code goes here }; {% endset %} {% include "snippets/esmCjsTabs.njk" %}

Note that plugins run as a second stage after the user’s primary configuration file has executed (to have access to the return object values).

If your plugin requires a specific feature in Eleventy, you should feature test it!

{% set codeContent %} export default function (eleventyConfig, pluginOptions) { if(!("addTemplate" in eleventyConfig)) { console.log( [my-test-plugin] WARN Eleventy plugin compatibility: Virtual Templates are required for this plugin, please use Eleventy v3.0 or newer. ); } }; {% endset %} {% include "snippets/esmCjsTabs.njk" %}

If feature testing is not available for your specific use case, you can add this code to your plugin configuration to show a warning if the plugin consumer does not have a compatible version of Eleventy:

{% set codeContent %} export default function (eleventyConfig, pluginOptions) { try { // Emit a warning message if the application is not using Eleventy 3.0 or newer (including prereleases). eleventyConfig.versionCheck(">=3.0"); } catch(e) { console.log( [my-test-plugin] WARN Eleventy plugin compatibility: ${e.message} ); } }; {% endset %} {% include "snippets/esmCjsTabs.njk" %}

• This uses the semver package and is compatible with advanced range syntax.
• Upper bounding your version number is not recommended. Eleventy works very hard to maintain backwards compatibility between major versions. Please ensure your plugin code does the same!
• The versionCheck method has been available in Eleventy core since v0.3.2 (~2018).

If you’re distributing your plugin as a package, consider following these conventions. These are not hard requirements.

• Add "eleventy-plugin" to your package.json’s keywords field.
• Prefix your package name with eleventy-plugin-
• Open a PR to add your plugin to our list of community plugins for publication on our community plugins directory.