Skip to navigation Skip to main content
Black Lives Matter
Eleventy
Eleventy Documentation
Stable
2.0.1
Canary
3.0.0-alpha.5
Toggle Menu
Eleventy 5.81s
Astro 12.52s

Configuration

Contents

Configuration files are optional. Add an .eleventy.js file to root directory of your project to configure Eleventy to your own project’s needs. It might look like this:

View this example in: CommonJS ESM
Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Return your Object options:
return {
dir: {
input: "views",
output: "dist"
}
}
};
Filename .eleventy.js
export default function(eleventyConfig) {
// Return your Object options:
return {
dir: {
input: "views",
output: "dist"
}
}
};

We support returning both a callback function (shown above) or an object literal (module.exports = {}). Callback functions are preferred and allow you further customization options using Eleventy’s provided helper methods.

Default filenames Jump to heading

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

We look for the following configuration files:

  1. .eleventy.js
  2. eleventy.config.js Added in v2.0.0
  3. eleventy.config.cjs Added in v2.0.0

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

Configuration Options Jump to heading

Input Directory Jump to heading

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.
Command Line Override --input

Examples Jump to heading

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
View this example in: CommonJS ESM
Filename .eleventy.js
module.exports = function(eleventyConfig) {
return {
dir: {
input: "views"
}
}
};
Filename .eleventy.js
export default function(eleventyConfig) {
return {
dir: {
input: "views"
}
}
};

Directory for Includes Jump to heading

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)
Command Line Override None

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
dir: {
// ⚠️ This value is relative to your input directory.
includes: "my_includes",
},
};
};

Directory for Layouts (Optional) Jump to heading

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)
Command Line Override None

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
dir: {
// ⚠️ These values are both relative to your input directory.
includes: "_includes",
layouts: "_layouts",
},
};
};

Directory for Global Data Files Jump to heading

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
Command Line Override None

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
dir: {
// ⚠️ This value is relative to your input directory.
data: "lore",
},
};
};

Output Directory Jump to heading

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.
Command Line Override --output

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
dir: {
output: "dist",
},
};
};

Default template engine for global data files Jump to heading

Default template engine for Markdown files Jump to heading

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

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
markdownTemplateEngine: "njk",
};
};

Default template engine for HTML files Jump to heading

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

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
htmlTemplateEngine: "njk",
};
};

Template Formats Jump to heading

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

Examples Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
templateFormats: ["html", "liquid", "njk"],
};
};
Filename .eleventy.js
module.exports = function (eleventyConfig) {
eleventyConfig.setTemplateFormats("html,liquid,njk");

// Or:
// eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
};
npx @11ty/eleventy --formats=html,liquid,njk
INFO:
Case sensitivity: File extensions should be considered case insensitive, cross-platform. While Mac OS—by default—already behaves this way, other operating systems do not and needed additional Eleventy code to enable this behavior.

Enable Quiet Mode to Reduce Console Noise Jump to heading

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 |

Example Jump to heading

Filename .eleventy.js
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 heading

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 links
Command Line Override --pathprefix

Example Jump to heading

Filename .eleventy.js
const { EleventyHtmlBasePlugin } = require("@11ty/eleventy");

module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(EleventyHtmlBasePlugin);

return {
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 exception case suffix for HTML files Jump to heading

If an HTML template has matching input and output directories, index.html files will have this suffix added to their output filename to prevent overwriting the template. Read more at the HTML template docs.

Exception Suffix
Object Key htmlOutputSuffix
Default -o
Valid Options Any valid string
Command Line Override None

Example Jump to heading

Filename .eleventy.js
module.exports = function (eleventyConfig) {
return {
htmlOutputSuffix: "-o",
};
};

Change Base File Name for Data Files Jump to heading

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
Filename .eleventy.js
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 heading

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 ([]).

Read more about Template and Directory Specific Data Files.

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

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

eleventyConfig.setDataFileSuffixes([]); // No data files are used.
};
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.

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

Transforms Jump to heading

Transforms can modify a template’s output. For example, use a transform to format/prettify an HTML file with proper whitespace.

The provided transform function must return the original or transformed content.

Transforms
Configuration API addTransform
Default {}
Valid Options Object literal
Command Line Override None
module.exports = function (eleventyConfig) {
// Can be sync or async
eleventyConfig.addTransform("transform-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);

return content; // no change done.
});
};
Transforms Example: Minify HTML Output
Filename .eleventy.js
const htmlmin = require("html-minifier");

module.exports = function (eleventyConfig) {
eleventyConfig.addTransform("htmlmin", function (content) {
// Prior to Eleventy 2.0: use this.outputPath instead
if (this.page.outputPath && this.page.outputPath.endsWith(".html")) {
let minified = htmlmin.minify(content, {
useShortDoctype: true,
removeComments: true,
collapseWhitespace: true,
});
return minified;
}

return content;
});
};

Linters Jump to heading

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
module.exports = function (eleventyConfig) {
// Can be 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.js
module.exports = 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 heading

Added in v1.0.0

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

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.

Type Definitions Jump to heading

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

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

Documentation Moved to Dedicated Pages Jump to heading

Copy Files to Output using Passthrough File Copy Jump to heading

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.

Data Deep Merge Jump to heading

Customize Front Matter Parsing Options Jump to heading

Watch JavaScript Dependencies Jump to heading

Add Your Own Watch Targets Jump to heading

Override Browsersync Server Options Jump to heading


Configuration: