Stable: 3.0.0
Canary: 3.0.1-alpha.5

Eleventy 1.93s

Next.js 70.65s

Configuration

Contents

Default filenames
Configuration Options

Configuration files are optional. Add an eleventy.config.js file to the root directory of your project (read more about default configuration filenames) to configure Eleventy to your own project’s needs. It might look like this:

eleventy.config.js

ESM CommonJS

export default async function(eleventyConfig) {
	// Configure Eleventy
};

module.exports = async function(eleventyConfig) {
	// Configure Eleventy
};

There are a few different ways to shape your configuration file. Added in v3.0.0Support for ESM and Asynchronous callbacks was added in Eleventy v3.0.

Add Filters.
Add Shortcodes.
Add Custom Tags.
Add JavaScript Functions
Add custom Collections and use Advanced Collection Filtering and Sorting.
Add some Plugins.

Is your config file getting big and hard to understand? You can create your own plugin to move some code out.

Default filenames

Jump to section titled: Default filenames

We look for the following configuration files:

.eleventy.js
eleventy.config.js Added in v2.0.0
eleventy.config.mjs Added in v3.0.0
eleventy.config.cjs Added in v2.0.0

The first configuration file found is used. The others are ignored.

Configuration Options

Jump to section titled: Configuration Options

Input Directory

Jump to section titled: Input Directory

Controls the top level directory/file/glob that we’ll use to look for templates.

Input Directory
Object Key	`dir.input`
Default Value	`.` (current directory)
Valid Options	Any valid directory.
Configuration API	`eleventyConfig.setInputDirectory()` Added in v3.0.0
Command Line Override	`--input`

Command Line

Jump to section titled: Command Line

# The current directory
npx @11ty/eleventy --input=.

# A single file
npx @11ty/eleventy --input=README.md

# A glob of files
npx @11ty/eleventy --input=*.md

# A subdirectory
npx @11ty/eleventy --input=views

Configuration

Jump to section titled: Configuration

Via named export (order doesn’t matter). Note that there are many different shapes of configuration file.

eleventy.config.js

ESM CommonJS

export const config = {
  dir: {
    input: "views"
  }
};

module.exports.config = {
  dir: {
    input: "views"
  }
};

Or via method (not available in plugins) Added in v3.0.0:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setInputDirectory("views");
};

module.exports = function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setInputDirectory("views");
};

Directory for Includes

Jump to section titled: Directory for Includes

The includes directory is meant for Eleventy layouts, include files, extends files, partials, or macros. These files will not be processed as full template files, but can be consumed by other templates.

Includes Directory
Object Key	`dir.includes`
Default	`_includes`
Valid Options	Any valid directory inside of `dir.input` (an empty string `""` is supported)
Configuration API	`eleventyConfig.setIncludesDirectory()` Added in v3.0.0
Command Line Override	None

Via named export (order doesn’t matter). Note that there are many different shapes of configuration file.

eleventy.config.js

ESM CommonJS

export const config = {
  dir: {
		// ⚠️ This value is relative to your input directory.
    includes: "my_includes"
  }
};

module.exports.config = {
  dir: {
		// ⚠️ This value is relative to your input directory.
    includes: "my_includes"
  }
};

Or via method (not available in plugins) Added in v3.0.0:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
	// This is relative to your input directory!
  eleventyConfig.setIncludesDirectory("my_includes");
};

module.exports = function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
	// This is relative to your input directory!
  eleventyConfig.setIncludesDirectory("my_includes");
};

Directory for Layouts (Optional)

Jump to section titled: Directory for Layouts (Optional)

This configuration option is optional but useful if you want your Eleventy layouts to live outside of the Includes directory. Just like the Includes directory, these files will not be processed as full template files, but can be consumed by other templates.

WARNING:

This setting only applies to Eleventy's language-agnostic layouts (when defined in front matter or data files).

When using {% extends %}, Eleventy will still search the _includes directory. See this note about existing templating features.

Includes Directory
Object Key	`dir.layouts`
Default	The value in `dir.includes`
Valid Options	Any valid directory inside of `dir.input` (an empty string `""` is supported)
Configuration API	`eleventyConfig.setLayoutsDirectory()` Added in v3.0.0
Command Line Override	None

Via named export (order doesn’t matter). Note that there are many different shapes of configuration file.

eleventy.config.js

ESM CommonJS

export const config = {
  dir: {
    // These are both relative to your input directory!
    includes: "_includes",
    layouts: "_layouts",
  }
};

module.exports.config = {
  dir: {
    // These are both relative to your input directory!
    includes: "_includes",
    layouts: "_layouts",
  }
};

Or via method (not available in plugins) Added in v3.0.0:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
	// This is relative to your input directory!
  eleventyConfig.setLayoutsDirectory("_layouts");
};

module.exports = function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
	// This is relative to your input directory!
  eleventyConfig.setLayoutsDirectory("_layouts");
};

Directory for Global Data Files

Jump to section titled: Directory for Global Data Files

Controls the directory inside which the global data template files, available to all templates, can be found. Read more about Global Data Files.

Data Files Directory
Object Key	`dir.data`
Default	`_data`
Valid Options	Any valid directory inside of `dir.input`
Configuration API	`eleventyConfig.setDataDirectory()` Added in v3.0.0
Command Line Override	None

Via named export (order doesn’t matter). Note that there are many different shapes of configuration file.

eleventy.config.js

ESM CommonJS

export const config = {
  dir: {
    // ⚠️ This value is relative to your input directory.
    data: "lore",
  }
};

module.exports.config = {
  dir: {
    // ⚠️ This value is relative to your input directory.
    data: "lore",
  }
};

Or via method (not available in plugins) Added in v3.0.0:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setDataDirectory("lore");
};

module.exports = function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setDataDirectory("lore");
};

Output Directory

Jump to section titled: Output Directory

Controls the directory inside which the finished templates will be written to.

Output Directory
Object Key	`dir.output`
Default	`_site`
Valid Options	Any string that will work as a directory name. Eleventy creates this if it doesn’t exist.
Configuration API	`eleventyConfig.setOutputDirectory()` Added in v3.0.0
Command Line Override	`--output`

Command Line

Jump to section titled: Command Line

npx @11ty/eleventy --output=_site

Configuration

Jump to section titled: Configuration

Via named export (order doesn’t matter). Note that there are many different shapes of configuration file.

eleventy.config.js

ESM CommonJS

export const config = {
  dir: {
		output: "dist",
  }
};

module.exports.config = {
  dir: {
		output: "dist",
  }
};

Or via method (not available in plugins) Added in v3.0.0:

eleventy.config.js

ESM CommonJS

export default function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setOutputDirectory("dist");
};

module.exports = function(eleventyConfig) {
	// Order matters, put this at the top of your configuration file.
  eleventyConfig.setOutputDirectory("dist");
};

Default template engine for Markdown files

Jump to section titled: Default template engine for Markdown files

Markdown files run through this template engine before transforming to HTML.

Markdown Template Engine
Object Key	`markdownTemplateEngine`
Default	`liquid`
Valid Options	A valid template engine short name or `false`
Command Line Override	None

eleventy.config.js

ESM CommonJS

export const config = {
  markdownTemplateEngine: "njk",
};

module.exports.config = {
  markdownTemplateEngine: "njk",
};

There are many different shapes of configuration file.

Default template engine for HTML files

Jump to section titled: Default template engine for HTML files

HTML templates run through this template engine before transforming to (better) HTML.

HTML Template Engine
Object Key	`htmlTemplateEngine`
Default	`liquid`
Valid Options	A valid template engine short name or `false`
Command Line Override	None

eleventy.config.js

ESM CommonJS

export const config = {
  htmlTemplateEngine: "njk",
};

module.exports.config = {
  htmlTemplateEngine: "njk",
};

There are many different shapes of configuration file.

Template Formats

Jump to section titled: Template Formats

Specify which types of templates should be transformed.

Template Formats
Object Key	`templateFormats`
Default	`html,liquid,ejs,md,hbs,mustache,haml,pug,njk,11ty.js`
Valid Options	Array of template engine short names
Command Line Override	`--formats` (accepts a comma separated string)
Configuration API	`setTemplateFormats` and `addTemplateFormats`

INFO:

Case sensitivity: File extensions should be considered case insensitive, cross-platform. While macOS already behaves this way (by default), other operating systems require additional Eleventy code to enable this behavior.

Command Line

Jump to section titled: Command Line

npx @11ty/eleventy --formats=html,liquid,njk

Configuration File Static Export

Jump to section titled: Configuration File Static Export

eleventy.config.js

ESM CommonJS

export const config = {
  templateFormats: ["html", "liquid", "njk"],
};

module.exports.config = {
  templateFormats: ["html", "liquid", "njk"],
};

There are many different shapes of configuration file.

Configuration API

Jump to section titled: Configuration API

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	// Reset to this value
	eleventyConfig.setTemplateFormats("html,liquid,njk");

	// Additive to existing
	eleventyConfig.addTemplateFormats("pug,haml");

	// Or:
	// eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
	// eleventyConfig.addTemplateFormats([ "pug", "haml" ]);
};

module.exports = function (eleventyConfig) {
	// Reset to this value
	eleventyConfig.setTemplateFormats("html,liquid,njk");

	// Additive to existing
	eleventyConfig.addTemplateFormats("pug,haml");

	// Or:
	// eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
	// eleventyConfig.addTemplateFormats([ "pug", "haml" ]);
};

Enable Quiet Mode to Reduce Console Noise

Jump to section titled: Enable Quiet Mode to Reduce Console Noise

In order to maximize user-friendliness to beginners, Eleventy will show each file it processes and the output file. To disable this noisy console output, use quiet mode!

Quiet Mode
Default	`false`
Valid Options	`true` or `false`
Command Line Override	`--quiet`

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	eleventyConfig.setQuietMode(true);
};

module.exports = function (eleventyConfig) {
	eleventyConfig.setQuietMode(true);
};

The command line will override any setting in configuration:

npx @11ty/eleventy --quiet

Deploy to a subdirectory with a Path Prefix

Jump to section titled: Deploy to a subdirectory with a Path Prefix

If your site lives in a different subdirectory (particularly useful with GitHub pages), use pathPrefix to specify this. When paired with the HTML <base> plugin it will transform any absolute URLs in your HTML to include this folder name and does not affect where things go in the output folder.

Path Prefix
Object Key	`pathPrefix`
Default	`/`
Valid Options	A prefix directory added to urls in HTML files
Command Line Override	`--pathprefix`

eleventy.config.js

ESM CommonJS

import { EleventyHtmlBasePlugin } from "@11ty/eleventy";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(EleventyHtmlBasePlugin);
};

export const config = {
	pathPrefix: "/eleventy-base-blog/",
}

module.exports = async function (eleventyConfig) {
	const { EleventyHtmlBasePlugin } = await import("@11ty/eleventy");

	eleventyConfig.addPlugin(EleventyHtmlBasePlugin);
};

module.exports.config = {
	pathPrefix: "/eleventy-base-blog/",
}

Deploy to https://11ty.github.io/eleventy-base-blog/ on GitHub pages without modifying your config. This allows you to use the same code-base to deploy to either GitHub pages or Netlify, like the eleventy-base-blog project does.

npx @11ty/eleventy --pathprefix=eleventy-base-blog

Change Base File Name for Data Files

Jump to section titled: Change Base File Name for Data Files

Added in v2.0.0 When using Directory Specific Data Files, looks for data files that match the current folder name. You can override this behavior to a static string with the setDataFileBaseName method.

File Suffix
Configuration API	`setDataFileBaseName`
Default	Current folder name
Valid Options	String
Command Line Override	None

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	// Looks for index.json and index.11tydata.json instead of using folder names
	eleventyConfig.setDataFileBaseName("index");
};

module.exports = function (eleventyConfig) {
	// Looks for index.json and index.11tydata.json instead of using folder names
	eleventyConfig.setDataFileBaseName("index");
};

Change File Suffix for Data Files

Jump to section titled: Change File Suffix for Data Files

Added in v2.0.0 When using Template and Directory Specific Data Files, to prevent file name conflicts with non-Eleventy files in the project directory, we scope these files with a unique-to-Eleventy suffix. This suffix is customizable using the setDataFileSuffixes configuration API method.

File Suffix
Configuration API	`setDataFileSuffixes`
Default	`[".11tydata", ""]`
Valid Options	Array
Command Line Override	None

For example, using ".11tydata" will search for *.11tydata.js and *.11tydata.json data files. The empty string ("") here represents a file without a suffix—and this entry only applies to *.json data files.

This feature can also be used to disable Template and Directory Data Files altogether with an empty array ([]).

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	// e.g. file.json and file.11tydata.json
	eleventyConfig.setDataFileSuffixes([".11tydata", ""]);

	// e.g. file.11tydata.json
	eleventyConfig.setDataFileSuffixes([".11tydata"]);

	// No data files are used.
	eleventyConfig.setDataFileSuffixes([]);
};

module.exports = function (eleventyConfig) {
	// e.g. file.json and file.11tydata.json
	eleventyConfig.setDataFileSuffixes([".11tydata", ""]);

	// e.g. file.11tydata.json
	eleventyConfig.setDataFileSuffixes([".11tydata"]);

	// No data files are used.
	eleventyConfig.setDataFileSuffixes([]);
};

Backwards Compatibility Note (v2.0.0)

Prior to v2.0.0 this feature was exposed using a jsDataFileSuffix property in the configuration return object. When the setDataFileSuffixes method has not been used, Eleventy maintains backwards compatibility for old projects by using this property as a fallback.

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	return {
		jsDataFileSuffix: ".11tydata",
	};
};

module.exports = function (eleventyConfig) {
	return {
		jsDataFileSuffix: ".11tydata",
	};
};

Transforms

Jump to section titled: Transforms

Documented moved to Transforms.

Linters

Jump to section titled: Linters

Similar to Transforms, Linters are provided to analyze a template’s output without modifying it.

Linters
Configuration API	`addLinter`
Object Key	N/A
Valid Options	Callback function
Command Line Override	None

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	// Sync or async
	eleventyConfig.addLinter("linter-name", async function (content) {
		console.log(this.inputPath);
		console.log(this.outputPath);

		// Eleventy 2.0+ has full access to Eleventy’s `page` variable
		console.log(this.page.inputPath);
		console.log(this.page.outputPath);
	});
};

module.exports = function (eleventyConfig) {
	// Sync or async
	eleventyConfig.addLinter("linter-name", async function (content) {
		console.log(this.inputPath);
		console.log(this.outputPath);

		// Eleventy 2.0+ has full access to Eleventy’s `page` variable
		console.log(this.page.inputPath);
		console.log(this.page.outputPath);
	});
};

Linters Example: Use Inclusive Language

Inspired by the CSS Tricks post Words to Avoid in Educational Writing, this linter will log a warning to the console when it finds a trigger word in a markdown file.

This example has been packaged as a plugin in eleventy-plugin-inclusive-language.

Filename eleventy.config.js

export default function (eleventyConfig) {
	eleventyConfig.addLinter(
		"inclusive-language",
		function (content, inputPath, outputPath) {
			let words =
				"simply,obviously,basically,of course,clearly,just,everyone knows,however,easy".split(
					","
				);

			// Eleventy 1.0+: use this.inputPath and this.outputPath instead
			if (inputPath.endsWith(".md")) {
				for (let word of words) {
					let regexp = new RegExp("\\b(" + word + ")\\b", "gi");
					if (content.match(regexp)) {
						console.warn(
							`Inclusive Language Linter (${inputPath}) Found: ${word}`
						);
					}
				}
			}
		}
	);
};

Data Filter Selectors

Jump to section titled: Data Filter Selectors

A Set of lodash selectors that allow you to include data from the data cascade in the output from --to=json, --to=ndjson.

eleventy.config.js

ESM CommonJS

export default function (eleventyConfig) {
	eleventyConfig.dataFilterSelectors.add("page");
	eleventyConfig.dataFilterSelectors.delete("page");
};

module.exports = function (eleventyConfig) {
	eleventyConfig.dataFilterSelectors.add("page");
	eleventyConfig.dataFilterSelectors.delete("page");
};

This will now include a data property in your JSON output that includes the page variable for each matching template.

TypeScript Type Definitions

Jump to section titled: TypeScript Type Definitions

This may enable some extra autocomplete features in your IDE (where supported).

eleventy.config.js

ESM CommonJS

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
export default function (eleventyConfig) {
	// …
};

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
module.exports = function (eleventyConfig) {
	// …
};

Related: GitHub #2091 and GitHub #3097

Removed Features

Jump to section titled: Removed Features

Change exception case suffix for HTML files

Jump to section titled: Change exception case suffix for HTML files

Feature Removal

The htmlOutputSuffix feature was removed in Eleventy 3.0. You can read about the feature on the v2 documentation. Related: GitHub #3327.

Documentation Moved to Dedicated Pages

Jump to section titled: Documentation Moved to Dedicated Pages

Copy Files to Output using Passthrough File Copy

Jump to section titled: Copy Files to Output using Passthrough File Copy

Files found (that don’t have a valid template engine) from opt-in file extensions in templateFormats will passthrough to the output directory. Read more about Passthrough Copy.

Documented at Transforms.

Configuration

Default filenames#

Configuration Options#

Input Directory#

Command Line#

Configuration#

Directory for Includes#

Directory for Layouts (Optional)#

Directory for Global Data Files#

Output Directory#

Command Line#

Configuration#

Default template engine for Markdown files#

Default template engine for HTML files#

Template Formats#

Command Line#

Configuration File Static Export#

Configuration API#

Enable Quiet Mode to Reduce Console Noise#

Deploy to a subdirectory with a Path Prefix#

Change Base File Name for Data Files#

Change File Suffix for Data Files#

Transforms#

Linters#

Data Filter Selectors#

TypeScript Type Definitions#

Removed Features#

Change exception case suffix for HTML files#

Documentation Moved to Dedicated Pages#

Copy Files to Output using Passthrough File Copy#

Data Deep Merge#

Customize Front Matter Parsing Options#

Watch JavaScript Dependencies#

Add Your Own Watch Targets#

Override Browsersync Server Options#

Transforms#

Other pages in Eleventy Documentation:

Default filenames

Configuration Options

Input Directory

Command Line

Configuration

Directory for Includes

Directory for Layouts (Optional)

Directory for Global Data Files

Output Directory

Command Line

Configuration

Default template engine for Markdown files

Default template engine for HTML files

Template Formats

Command Line

Configuration File Static Export

Configuration API

Enable Quiet Mode to Reduce Console Noise

Deploy to a subdirectory with a Path Prefix

Change Base File Name for Data Files

Change File Suffix for Data Files

Transforms

Linters

Data Filter Selectors

TypeScript Type Definitions

Removed Features

Change exception case suffix for HTML files

Documentation Moved to Dedicated Pages

Copy Files to Output using Passthrough File Copy

Data Deep Merge

Customize Front Matter Parsing Options

Watch JavaScript Dependencies

Add Your Own Watch Targets

Override Browsersync Server Options

Transforms