Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
Eleventy, 2024 in Review
Versions
Stable
3.0.0
Canary
3.0.1-alpha.4
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Plugins

Contents

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

Plugins are Configuration

At their simplest, Eleventy plugins are a function passed to the addPlugin method.

eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.addPlugin(function(eleventyConfig) {
		// I am a plugin!
	});
};
module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(function(eleventyConfig) {
		// I am a plugin!
	});
};

The plugin can be defined elsewhere in the same file:

eleventy.config.js
function myPlugin(eleventyConfig) {
	// I am a plugin!
}

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(myPlugin);
};
function myPlugin(eleventyConfig) {
	// I am a plugin!
}

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(myPlugin);
};

Or in a different file:

eleventy.config.js
import myPlugin from "./_config/plugin.js";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(myPlugin);
};
const myPlugin = require("./_config/plugin.js");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(myPlugin);
};

Or in an npm package:

eleventy.config.js
import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};
const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};

Plugins are async-friendly Added in v3.0.0 but you must await the addPlugin method.

eleventy.config.js
export default async function (eleventyConfig) {
	await eleventyConfig.addPlugin(async function(eleventyConfig) {
		// I am an asynchronous plugin!
	});
};
module.exports = async function (eleventyConfig) {
	await eleventyConfig.addPlugin(async function(eleventyConfig) {
		// I am an asynchronous plugin!
	});
};

安装插件

Installation

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

在配置文件中为 Eleventy 添加插件

你的配置文件可能被命名为 eleventy.config.js 或 .eleventy.js。

eleventy.config.js
import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};
const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginRss);
};

插件的配置参数

为 addPlugin 函数设置第二个参数（可选）来自定义插件的行为。这一参数是特定于插件的。请查阅相应插件的文档 (例如，eleventy-plugin-syntaxhighlight 的 README 文件) 以了解其支持哪些参数。

eleventy.config.js
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!
		},
	});
};
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.

eleventy.config.js
import pluginRss from "@11ty/eleventy-plugin-rss";

export default function (eleventyConfig) {
	eleventyConfig.namespace("myPrefix_", () => {
		// the rssLastUpdatedDate filter is now myPrefix_rssLastUpdatedDate
		eleventyConfig.addPlugin(pluginRss);
	});
};
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:
插件的命名空间是 Eleventy 赋予网站程序的功能，不能用在你自己创建的插件（配置）中。请查看 Issue #256。

Advanced: Execute a plugin immediately Added in v3.0.0

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.

eleventy.config.js
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");
};
module.exports = function (eleventyConfig, pluginOptions) {
	console.log( "first" );

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

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

	console.log("third");
};

Creating a Plugin

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:

plugin.js
export default function (eleventyConfig, pluginOptions) {
	// Your plugin code goes here
};
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

plugin-with-args.js
export default {
	initArguments: {},
	configFunction: function (eleventyConfig, pluginOptions) {
		// Your plugin code goes here
	},
};
module.exports = {
	initArguments: {},
	configFunction: function (eleventyConfig, pluginOptions) {
		// Your plugin code goes here
	},
};
eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.addPlugin(require("./fancy-plugin.js"), {
		init: function (initArguments) {
			// `this` is the eleventyConfig object
			// initArguments will be the `myInitArguments` object from above
		},
	});
};
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

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

plugin.js
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.` );
	}
};
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

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:

plugin.js
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}` );
	}
};
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}` );
	}
};
  • 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).

Distributing a Plugin

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

Plugins: