Configuration Jump to heading
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.
Configuration Options Jump to heading
- Configuration Options
- 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
- Enable Quiet Mode to Reduce Console Noise
- Deploy to a subdirectory with a Path Prefix
- Change exception case suffix for HTML files
- Change File Suffix for Template and Directory Data Files
- Transforms
- Linters
- Data Filter Selectors
- Documentation Moved to Dedicated Pages
Input Directory Jump to heading
Controls the top level directory/file/glob 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 |
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.
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 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.
This setting only applies to Eleventy's language-agnostic layouts (when defined in front matter or data files).
When using {% extends %}
, 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 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.
Data Files Directory | |
---|---|
Object Key | dir.data |
Default | _data |
Valid Options | Any valid directory inside of dir.input |
Command Line Override | None |
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.
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 Jump to heading
module.exports = function(eleventyConfig) {
return {
dir: {
output: "dist"
}
}
};
Default template engine for global data files Jump to heading
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 Jump to heading
module.exports = function(eleventyConfig) {
return {
"dataTemplateEngine": "njk"
}
};
Default template engine for Markdown files Jump to heading
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 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.
HTML Template Engine | |
---|---|
Object Key | htmlTemplateEngine |
Default | liquid |
Valid Options | A valid template engine short name or false |
Command Line Override | None |
Example Jump to heading
module.exports = function(eleventyConfig) {
return {
htmlTemplateEngine: "njk"
}
};
Template Formats Jump to heading
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 |
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!
Quiet Mode | |
---|---|
Default | false |
Valid Options | true or false |
Command Line Override | --quiet |
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.
Path Prefix | |
---|---|
Object Key | pathPrefix |
Default | / |
Valid Options | A prefix directory added to links |
Command Line Override | --pathprefix |
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.
Exception Suffix | |
---|---|
Object Key | htmlOutputSuffix |
Default | -o |
Valid Options | Any valid string |
Command Line Override | None |
Example Jump to heading
module.exports = function(eleventyConfig) {
return {
htmlOutputSuffix: "-o"
}
};
Change File Suffix for Template and Directory Data Files Jump to heading
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 Jump to heading
module.exports = function(eleventyConfig) {
return {
jsDataFileSuffix: ".11tydata"
}
};
Transforms Jump to heading
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.
The provided transform function must return the original or transformed content.
Transforms | |
---|---|
Object Key | filters (Removed in 1.0, use addTransform instead) |
Default | {} |
Valid Options | Object literal |
Command Line Override | None |
Configuration API | addTransform |
module.exports = function(eleventyConfig) {
eleventyConfig.addTransform("transform-name", function(content, outputPath) {
return content; // no change done.
});
eleventyConfig.addTransform("async-transform-name", async function(content, outputPath) {
return content; // no change done.
});
// 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
return content; // no change done.
});
};
Transforms Example: Minify HTML Output Jump to heading
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 Jump to heading
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 |
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 Jump to heading
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 Jump to heading
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 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.