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
• Add custom Collections and use Advanced Collection Filtering and Sorting.
• Add some Plugins.

Default filenames Jump to heading #

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.

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

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

Example Jump to heading #

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.

Example Jump to heading #

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.

Example Jump to heading #

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.

Example Jump to heading #

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.

Example Jump to heading #

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.

Example Jump to heading #

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

Template Formats Jump to heading #

Specify which types of templates should be transformed.

Examples Jump to heading #

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 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!

Example Jump to heading #

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. 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 Jump to heading #

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

Example Jump to heading #

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.

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.

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.

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.
};

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.

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

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.

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 );
  });
};

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) {
  // …
};

• More background information at Issue 2091.

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 #

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

Customize Front Matter Parsing Options Jump to heading #

• Documented at Customize Front Matter Parsing.

Watch JavaScript Dependencies Jump to heading #

• Documented at Watch and Serve Configuration.

Add Your Own Watch Targets Jump to heading #

• Documented at Watch and Serve Configuration.

Override Browsersync Server Options Jump to heading #

• 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
  • Eleventy Dev Server
  • Browsersync
  • Vite