Skip to navigation Skip to main content
We The Protesters
Eleventy
Eleventy Documentation
Stable
2.0.1
Canary
3.0.0-alpha.6
Toggle Menu
Eleventy 5.81s
Gatsby 43.36s

Plugins

Contents

Plugins are custom code that Eleventy can import into a project from an external repository.

Adding a Plugin Jump to heading

Installation Jump to heading

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

Add the plugin to Eleventy in your config file Jump to heading

Your config file is probably named .eleventy.js.

Filename .eleventy.js
const pluginRss = require("@11ty/eleventy-plugin-rss");
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(pluginRss);
};

Plugin Configuration Options Jump to heading

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.

const pluginSyntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(pluginSyntaxHighlight, {
// only install the markdown highlighter
templateFormats: ["md"],

init: function ({ Prism }) {
// Add your own custom language to Prism!
},
});
};
Advanced Usage: Namespacing a plugin

It’s unlikely you’ll need this feature but you can namespace parts of your configuration using eleventyConfig.namespace. This will add a string prefix to all filters, tags, helpers, shortcodes, collections, and transforms.

Filename .eleventy.js
const pluginRss = require("@11ty/eleventy-plugin-rss");
module.exports = function (eleventyConfig) {
eleventyConfig.namespace("myPrefix_", () => {
// the rssLastUpdatedDate filter is now myPrefix_rssLastUpdatedDate
eleventyConfig.addPlugin(pluginRss);
});
};
WARNING:
Plugin namespacing is an application feature and should not be used if you are creating your own plugin (in your plugin configuration code). Follow along at Issue #256.

Creating a Plugin Jump to heading

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.js file is passed here), in addition to any config passed by the user:

Filename plugin.js
module.exports = function (eleventyConfig, pluginOptions) {
// Your plugin code goes here
};

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).

Advanced Usage: Custom Plugin Arguments

If you want to allow developers to use custom arguments provided by your plugin, you can export an object. Prefer using the above syntax unless you need this behavior. For an example of how this is used, see the syntax highlighting plugin

Filename fancy-plugin.js
module.exports = {
initArguments: {},
configFunction: function (eleventyConfig, pluginOptions) {
// Your plugin code goes here
},
};
Filename .eleventy.js
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(require("./fancy-plugin.js"), {
init: function (initArguments) {
// `this` is the eleventyConfig object
// initArguments will be the `myInitArguments` object from above
},
});
};

Feature Testing Jump to heading

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

module.exports = 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.` );
}
};

Version Checking Jump to heading

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:

module.exports = 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}` );
}
};

Distributing a Plugin Jump to heading

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


Plugins: