11ty

Eleventy Documentation

⚠️ This documentation is for an older version. Go to the newest Eleventy docs or check out the full release history.

Documentation Pages

Configuration #

Configuration is an optional feature. Add an .eleventy.js file to root directory of your project to override these configuration options with your own preferences.

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

Using the Configuration API #

If you expose your config as a function instead of an object literal, we’ll pass in a config argument that you can use!

module.exports = function(eleventyConfig) {
// Add a filter using the Config API
eleventyConfig.addFilter( "myFilter", function() {});
// You can return your Config object (optional).
return {
dir: {
input: "views"
}
};
};

This allows you further customization options using Eleventy’s provided helper methods.

Add Tags/Filters #

Read more about Tags and Filters

Add Collections #

Read more about Collections and Advanced Collection Filtering and Sorting.

Use Plugins #

Read more about Plugins.

Configuration Options #

Input Directory #

Controls the top level directory 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

Example #

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

Directory for Includes #

Controls the directory inside which the template includes/extends/partials/etc can be found.

Includes Directory
Object Key dir.includes
Default _includes
Valid Options Any valid directory inside of dir.input
Command Line Override None

Example #

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

Directory for Global Data Files #

Controls the directory inside which the global data template files, available to all templates, can be found.

Data Files Directory
Object Key dir.data
Default _data
Valid Options Any valid directory inside of dir.input
Command Line Override None

Example #

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

Output Directory #

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

Output Directory
Object Key dir.data
Default _data
Valid Options Any string that will work as a directory name. Eleventy creates this if it doesn’t exist.
Command Line Override --output

Example #

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

Default template engine for global data files #

The data.dir global data files run through this template engine before transforming to JSON.

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

Example #

module.exports = {
    "dataTemplateEngine": "njk"
};

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

Example #

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

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

Example #

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

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
Valid Options Array of template engine short names
Command Line Override --formats (accepts a comma separated string)
Configuration API setTemplateFormats (New in Eleventy v0.2.14)

Examples #

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

    // Or:
    // eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
};
eleventy --formats=html,liquid,njk

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. It’s used by the url filter and inserted at the beginning of all absolute url href links. It does not affect your file structure. Leading or trailing slashes are all normalized away, so don’t worry about it.

Path Prefix
Object Key pathPrefix
Default /
Valid Options A prefix directory added to links
Command Line Override --pathprefix (New in Eleventy v0.2.11)

Example #

module.exports = {
    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.

eleventy --pathprefix=eleventy-base-blog

Copy Files to Output using Pass-through File Copy #

Files found (that don’t have a valid template engine) from white-listed file extensions (in templateFormats) will pass-through to the output directory. Read more about Pass-through Copy.

Pass-through Copy
Object Key passthroughFileCopy
Default true
Valid Options true or false
Command Line Override None

Example #

module.exports = {
    passthroughFileCopy: false
};

Change exception case suffix for HTML files #

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 Common Pitfalls.

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

Transforms #

(These used to be called Filters but were renamed to Transforms, so they’re not confused with Template Filters).

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

Transforms
Object Key filters (Deprecated and renamed, use the Configuration API instead)
Default {}
Valid Options Object literal
Command Line Override None
Configuration API addTransform (This is definitely available in Eleventy v0.3.3 but was likely in earlier versions as well)

Example #

module.exports = function(eleventyConfig) {
  eleventyConfig.addTransform( "doNothing", function(str, outputPath) {
    return str;
  });
};