Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
582 lines (431 sloc) 16.4 KB
subtitle menuSectionName submenuSortOrder tags
Configuration
docs-config
copy
ignores
filters
shortcodes
custom-tags
plugins
docs

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.

Configuration Options

Jump to:

{% set toc = [ "Input Directory", "Directory for Includes", "Directory for Layouts (Optional)", "Directory for Global Data Files", "Output Directory", "Default Template Engine for Global Data Files", "Default Template Engine for Markdown Files", "Default Template Engine for HTML Files", "Template Formats", "Deploy to a Subdirectory with a Path Prefix", "Copy Files to Output using Pass-through File Copy", "Change Exception Case Suffix for HTML Files", "Change File Suffix for Template and Directory Data Files", "Transforms", "Linters", "Data Deep Merge", "Watch JavaScript Dependencies", "Override Browsersync Server Options" ] %} {%- for link in toc %}

  • [{{ link }}](#{{ link | slug }}) {%- endfor %}

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
eleventy --input=.

# A single file
eleventy --input=README.md

# A glob of files (New in v0.6.0)
eleventy --input=*.md

# A subdirectory
eleventy --input=views
Configuration

{% codetitle ".eleventy.js" %}

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

Directory for Includes

The includes directory is meant for layout templates, include files, extends files, partials, or macros. These files will not be processed as input 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" %}

The layouts directory is optional and intended only for projects that don’t want their layout templates to live in the Includes directory. These files will not be processed as input files, but can be consumed by other templates.

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 data.dir 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
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
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" ]);
};
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 {% 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.

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

{% codetitle ".eleventy.js" %}

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 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(chalk.yellow(`Inclusive Language Linter (${inputPath}) Found: ${word}`));
        }
      }
    }
  });
};

Data Deep Merge {% addedin "0.6.0" %}

Opts in to a full deep merge when combining the Data Cascade. This will use something like lodash.mergewith to combine Arrays and deep merge Objects, rather than a simple top-level merge using Object.assign. Read more at Issue #147. This will likely become the default in an upcoming major version.

{% codetitle ".eleventy.js" %}

module.exports = function(eleventyConfig) {
  eleventyConfig.setDataDeepMerge(true);
};

Note that all data stored in the pagination variable is exempted from this behavior (we don’t want pagination.items to be merged together).

Using the override: prefix

Use the override: prefix on any data key to opt-out of this merge behavior for specific values or nested values.

{% codetitle "posts/posts.json" %}

{
  "tags": ["posts"]
}

{% codetitle "posts/firstpost.md" %}

---
override:tags: []
---

Even though normally the posts/firstpost.md file would inherit the posts tag from the directory data file (per normal data cascade rules), we can override the tags value to be an empty array to opt-out of this behavior.

Watch JavaScript Dependencies {% addedin "0.7.0" %}

When in --watch mode, Eleventy will spider the dependencies of your JavaScript Templates (.11ty.js), JavaScript Data Files (.11tydata.js or _data/**/*.js), or Configuration File (usually .eleventy.js) to watch those files too. Files in node_modules directories are ignored. This feature is enabled by default.

{% codetitle ".eleventy.js" %}

module.exports = function(eleventyConfig) {
  // Enabled by default
  eleventyConfig.setWatchJavaScriptDependencies(false);
};

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

Useful if you want to change or override the default Browsersync configuration. Find the Eleventy defaults in EleventyServe.js. Take special note that Eleventy does not use Browsersync’s watch options and trigger reloads manually after our own internal watch methods are complete. See full options list on the Browsersync documentation.

(Read more at Issue #123)

{% codetitle ".eleventy.js" %}

module.exports = function(eleventyConfig) {
  eleventyConfig.setBrowserSyncConfig({
    notify: true
  });
};
You can’t perform that action at this time.