Configuration #

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:

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

• Add Filters.
• Add Shortcodes.
• Add Custom Tags.
• Add JavaScript Functions New in v0.7.0
• Add custom Collections and use Advanced Collection Filtering and Sorting.
• Add some Plugins.

Configuration Options #

Input Directory #

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

Glob support is New in v0.6.0.

Examples #

Command Line

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

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

# A glob of files (New in v0.6.0)
npx @11ty/eleventy --input=*.md

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

Configuration

module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "views"
    }
  }
};

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.

Example #

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

Directory for Layouts (Optional) New in v0.8.0 #

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.

Example #

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

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.

Example #

module.exports = function(eleventyConfig) {
  return {
    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.

Example #

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

Default template engine for global data files #

The dir.data global data files run through this template engine before transforming to JSON. Read more about Global Data Files.

Example #

module.exports = function(eleventyConfig) {
  return {
    "dataTemplateEngine": "njk"
  }
};

Default template engine for Markdown files #

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

Example #

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

Default template engine for HTML files #

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

Example #

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

Template Formats #

Specify which types of templates should be transformed.

Examples #

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

module.exports = function(eleventyConfig) {
    eleventyConfig.setTemplateFormats("html,liquid,njk");

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

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

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!

New in v0.10.0 This configuration API method (setQuietMode) was added in v0.10.0 but note that the --quiet command line override existed long before that.

New in v0.10.0 Added --quiet=false to override setQuietMode(true) on the command line (for deploys in production). --quiet=true was also added (same as --quiet).

Example #

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 #

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.

Example #

module.exports = function(eleventyConfig) {
  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 #

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.

Example #

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

Change File Suffix for Template and Directory Data Files New in v0.5.3 #

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 key is customizable using jsDataFileSuffix. For example, using .11tydata for this value will search for *.11tydata.js and *.11tydata.json data files. Read more about Template and Directory Specific Data Files.

Example #

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

Transforms #

These used to be called Filters but were renamed to Transforms to avoid confusion with Template Language Filters.

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

module.exports = function(eleventyConfig) {
  eleventyConfig.addTransform("transform-name", function(content, outputPath) {});

  // Support for async transforms was added in 0.7.0
  eleventyConfig.addTransform("async-transform-name", async function(content, outputPath) {});

  // Eleventy 1.0+
  eleventyConfig.addTransform("transform-name", function(content) {
    console.log( this.inputPath );
    console.log( this.outputPath );

    // note that this.outputPath is `false` for serverless templates
  });
};

Transforms Example: Minify HTML Output #

const htmlmin = require("html-minifier");

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

    return content;
  });
};

Linters #

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

module.exports = function(eleventyConfig) {
  eleventyConfig.addLinter("linter-name", function(content, inputPath, outputPath) {});
  eleventyConfig.addLinter("async-linter-name", async function(content, inputPath, outputPath) {});

  // Eleventy 1.0+
  eleventyConfig.addLinter("linter-name", function(content) {
    console.log( this.inputPath );
    console.log( this.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.

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 #

New 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.

Documentation Moved to Dedicated Pages #

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.

Data Deep Merge New in v0.6.0 #

• Documentation for Data Deep Merging has been moved to its own page under the Data Cascade.

Customize Front Matter Parsing Options New in v0.9.0 #

• Documented at Customize Front Matter Parsing.

Watch JavaScript Dependencies New in v0.7.0 #

• Documented at Watch and Serve Configuration.

Add Your Own Watch Targets New in v0.10.0 #

• Documented at Watch and Serve Configuration.

Override Browsersync Server Options New in v0.7.0 #

• Documented at Watch and Serve Configuration.

Configuration:

• Passthrough File Copy
• Ignore Files
• Filters
  • url
  • slugify
  • log
  • get*CollectionItem
• Shortcodes
• Custom Tags
• Events
• Watch and Serve