eleventyNavigation

key	order
Configuration	6

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.

{% codetitle ".eleventy.js" %}

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!

{% codetitle ".eleventy.js" %}

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 Filters.
Add Shortcodes.
Add Custom Tags.
Add JavaScript Functions {% addedin "0.7.0" %}
Add custom Collections and use Advanced Collection Filtering and Sorting.
Add some Plugins.

Configuration Options

[[toc]]

Input Directory

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

Glob support is {% addedin "0.6.0" %}.

Input Directory
Object Key	`dir.input`
Default Value	`.` (current directory)
Valid Options	Any valid directory.
Command Line Override	`--input`

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

{% codetitle ".eleventy.js" %}

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

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

{% codetitle ".eleventy.js" %}

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

Directory for Layouts (Optional) {% addedin "0.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.

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

When using {% raw %}{% extends %}{% endraw %}, 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

{% codetitle ".eleventy.js" %}

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

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

Example

{% codetitle ".eleventy.js" %}

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

{% codetitle ".eleventy.js" %}

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

Data Template Engine
Object Key	`dataTemplateEngine`
Default	`"liquid"` (before 1.0)
Default	`false` (1.0 and above)
Valid Options	A valid template engine short name or `false`
Command Line Override	None

Example

{% codetitle ".eleventy.js" %}

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

{% codetitle ".eleventy.js" %}

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

{% codetitle ".eleventy.js" %}

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,11ty.js`
Valid Options	Array of template engine short names
Command Line Override	`--formats` (accepts a comma separated string)
Configuration API	`setTemplateFormats` {% addedin "0.2.14" %}

Examples

{% codetitle ".eleventy.js" %}

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

{% codetitle ".eleventy.js" %}

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

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

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

{% callout "info" %}{% addedin "0.9.0" %} 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.{% endcallout %}

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!

Path Prefix
Default	`false`
Valid Options	`true` or `false`
Command Line Override	`--quiet`

{% addedin "0.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.

{% addedin "0.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

{% codetitle ".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

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` {% addedin "0.2.11" %}

Example

{% codetitle ".eleventy.js" %}

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.

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.

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

Example

{% codetitle ".eleventy.js" %}

module.exports = {
    htmlOutputSuffix: "-o"
};

Change File Suffix for Template and Directory Data Files {% addedin "0.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.

File Suffix
Object Key	`jsDataFileSuffix`
Default	`.11tydata`
Valid Options	Any valid string
Command Line Override	None

Example

{% codetitle ".eleventy.js" %}

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

Transforms
Object Key	`filters` (Deprecated and renamed, use the Configuration API instead)
Default	`{}`
Valid Options	Object literal
Command Line Override	None
Configuration API	`addTransform` {% addedin "0.3.3" %}

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

Transforms Example: Minify HTML Output

{% codetitle ".eleventy.js" %}

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

module.exports = function(eleventyConfig) {
  eleventyConfig.addTransform("htmlmin", function(content, outputPath) {
    if( 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.

Linters
Object Key	N/A
Valid Options	Callback function
Command Line Override	None
Configuration API	`addLinter` {% addedin "0.5.4" %}

module.exports = function(eleventyConfig) {
  eleventyConfig.addLinter("linter-name", function(content, inputPath, outputPath) {});
  eleventyConfig.addLinter("async-linter-name", async function(content, inputPath, 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.

{% codetitle ".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(",");
    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}`);
        }
      }
    }
  });
};

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. This feature is enabled by default and can be disabled.

Data Deep Merge {% addedin "0.6.0" %}

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

Customize Front Matter Parsing Options {% addedin "0.9.0" %}

Documented at Customize Front Matter Parsing.

Watch JavaScript Dependencies {% addedin "0.7.0" %}

Documented at Watch and Serve Configuruation.

Add Your Own Watch Targets {% addedin "0.10.0" %}

Documented at Watch and Serve Configuruation.

Override Browsersync Server Options {% addedin "0.7.0" %}

Documented at Watch and Serve Configuruation.

Files

config.md

Latest commit

History

config.md

File metadata and controls

Configuration

Using the Configuration API

Configuration Options

Input Directory

Examples

Command Line

Configuration

Directory for Includes

Example

Directory for Layouts (Optional) {% addedin "0.8.0" %}

Example

Directory for Global Data Files

Example

Output Directory

Example

Default template engine for global data files

Example

Default template engine for Markdown files

Example

Default template engine for HTML files

Example

Template Formats

Examples

Enable Quiet Mode to Reduce Console Noise

Example

Deploy to a subdirectory with a Path Prefix

Example

Change exception case suffix for HTML files

Example

Change File Suffix for Template and Directory Data Files {% addedin "0.5.3" %}

Example

Transforms

Transforms Example: Minify HTML Output

Linters

Linters Example: Use Inclusive Language

Documentation Moved to Dedicated Pages

Copy Files to Output using Passthrough File Copy

Data Deep Merge {% addedin "0.6.0" %}

Customize Front Matter Parsing Options {% addedin "0.9.0" %}

Watch JavaScript Dependencies {% addedin "0.7.0" %}

Add Your Own Watch Targets {% addedin "0.10.0" %}

Override Browsersync Server Options {% addedin "0.7.0" %}