Plugins
Contents
Plugins are custom code that Eleventy can import into a project from an external repository.
- Official Eleventy Plugins (look for the
@11ty/
prefix on npm) - Community Contributed Plugins
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
.
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.
const pluginRss = require("@11ty/eleventy-plugin-rss");
module.exports = function (eleventyConfig) {
eleventyConfig.namespace("myPrefix_", () => {
// the rssLastUpdatedDate filter is now myPrefix_rssLastUpdatedDate
eleventyConfig.addPlugin(pluginRss);
});
};
Creating a Plugin Jump to heading
A plugin primarily provides a “configuration function.” This function is called when Eleventy is first initialized, and takes the same eleventyConfig
object as the user’s .eleventy.js
file gets, in addition to any config passed by the user:
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
module.exports = {
initArguments: {},
configFunction: function (eleventyConfig, pluginOptions) {
// Your plugin code goes here
},
};
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
},
});
};
Distributing a Plugin Jump to heading
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’skeywords
field. - Prefix your package name with
eleventy-plugin-
- Write your plugin code in a
.eleventy.js
file in the root of your repository, and set the"main"
field of your package.json to".eleventy.js"
- Open a PR to add your plugin to our list of community plugins <3