A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.
Works with:
- HTML (
.html) - Markdown (
.md) (usingmarkdown-it) - Liquid (
.liquid) (used by Jekyll) - Nunjucks (
.njk) - Handlebars (
.hbs) - Mustache (
.mustache) - EJS (
.ejs) - Haml (
.haml) - Pug (formerly Jade,
.pug) - JavaScript Template Literals (
.jstl) (`strings with backticks`)
Requires version 8 of Node.js or higher.
npm install -g @11ty/eleventy
Available on npm. Previously known as eleventy-cli. Read more about local installation.
Make a directory with your project in it. Don’t include the first $ when you run these commands.
$ mkdir eleventy-sample
$ cd eleventy-sample
Run eleventy:
$ eleventy
Wrote 0 files in 0.02 seconds
Makes sense—this is an empty folder with no templates inside. So, let’s make a few templates.
$ echo "<!doctype html><title>Page title</title>" > index.html
$ echo "# Page header" > README.md
We’ve now created an HTML template and a markdown template. Now run eleventy again:
$ eleventy
Writing _site/README/index.html from ./README.md
Writing _site/index.html from ./index.html
Wrote 2 files in 0.10 seconds
This will compile any content templates in the current directory or subdirectories into the output folder (defaults to _site). Congratulations—you made something with eleventy! Now put it to work with templating syntax, front matter, and data files (read on below).
- eleventy-base-blog: How to build a blog web site with Eleventy.
- @Heydon’s lovely Inclusive Web Design Checklist, converted to use
eleventy. The original project took a JSON file and converted it HTML with some one-off JavaScript. This uses eleventy to transform the data using a nunjucks template, resulting in a cleaner, templated setup. - 11ty-logo generates a template with
eleventythat has hundreds of different font combinations in an attempt to pick a logo. - Have a suggestion? File an issue!
# Searches the current directory, outputs to ./_site
eleventy
# Equivalent to
eleventy --input=. --output=_site
# Automatically run when input template files change.
eleventy --watch
# Override the default eleventy project config filename (.eleventy.js)
eleventy --config=myeleventyconfig.js
# Use only a subset of template types
eleventy --formats=md,html,ejs
# Find out the most up-to-date list of commands (there are more)
eleventy --help
Having trouble? Want to see what Eleventy is doing behind the scenes? Use DEBUG mode. We’re taking advantage of the excellent debug package for this. Enable with the DEBUG env variable, either specific to eleventy (DEBUG=Eleventy*) or globally (DEBUG=*):
DEBUG=Eleventy* eleventy
This will tell you exactly what directories Eleventy is using for data, includes, input, and output. It’ll tell you what search globs it uses to find your templates and what templates it finds. If you’re having trouble, enable this.
A small sample of the output:
Eleventy Directories:
Eleventy Input: docs-src
Eleventy Data: docs-src/_data
Eleventy Includes: docs-src/_includes
Eleventy Output: docs
Eleventy Template Formats: njk
Read more at the debug package documentation.
eleventy --input=. --output=_site
A template.md in the current directory will be rendered to _site/template/index.html. Read more at Permalinks
Yes, you can use the same input and output directories, like so:
# Parse and write Markdown to HTML, respecting directory structure.
eleventy --input=. --output=. --formats=md
--formats=html here! If you run eleventy more than once, it’ll try to process the output files too. Read more at Common Pitfalls.
You may use front matter on any template file to add local data. Front matter looks like this:
---
title: My page title
---
<!doctype html>
<html>
…
This allows you to assign data values right in the template itself. Here are a few front matter keys that we use for special things:
permalink: Add in front matter to change the output target of the current template. You can use template syntax for variables here. Read more about Permalinks.layout: Wrap current template with a layout template found in the_includesfolder. Read more about Layouts.pagination: Enable to iterate over data. Output multiple HTML files from a single template. Read more about Pagination.tags: A single string or array that identifies that a piece of content is part of a collection. Collections can be reused in any other template. Read more about Collections.date: Override the default date (file creation) to customize how the file is sorted in a collection. Read more about Collections.
pkg: The local project’spackage.jsonvalues.pagination: (When enabled in front matter) Read more about Pagination.collections: Lists of all of your content, grouped by tags. Read more about Collectionspage: Has information about the current page. Currently holds:{ url: "/current/page/url.html" }. Useful for finding the current page in a collection. Read more about Collections (look at Example: Navigation Links with anactiveclass added for on the current page).
Optionally add data files to add global static data available to all templates. Uses the dir.data configuration option. Read more about Template Data Files.
Add an .eleventyignore file to the root of your input directory for a new line-separated list of files that will not be processed. Paths listed in your project’s .gitignore file are automatically ignored.
Add an .eleventy.js file to root directory of your project to override these configuration options with your own preferences. Example:
module.exports = {
dir: {
input: "views"
}
};
| Configuration Option Key | Default Option | Valid Options | Command Line Override | Description |
|---|---|---|---|---|
dir.input |
. |
Any valid directory. | --input |
Controls the top level directory inside which the templates should be found. |
dir.includes |
_includes |
Any valid directory inside of dir.input. |
N/A | Controls the directory inside which the template includes/extends/partials/etc can be found. |
dir.data |
_data |
Any valid directory inside of dir.input. |
N/A | Controls the directory inside which the global data template files, available to all templates, can be found. |
dir.output |
_site |
Any valid directory. | --output |
Controls the directory inside which the transformed finished templates can be found. |
dataTemplateEngine |
liquid |
A valid template engine or false |
N/A | Run the data.dir global data files through this template engine before transforming it to JSON. |
markdownTemplateEngine |
liquid |
A valid template engine or false |
N/A | Run markdown through this template engine before transforming it to HTML. |
htmlTemplateEngine |
liquid |
A valid template engine or false |
N/A | Run HTML templates through this template engine before transforming it to (better) HTML. |
templateFormats |
liquid,ejs, md,hbs, mustache,haml, pug,njk,html |
Any combination of these | --formats |
Specify which type of templates should be transformed. |
pathPrefix |
/ |
A prefix directory added to links | N/A | Used by the url filter and inserted at the beginning of all href links. Use if your blog lives in a subdirectory outside of eleventy’s control. |
passthroughFileCopy |
true |
true or false |
N/A | Files found (that aren’t templates) from white-listed file extensions will pass-through to the output directory. Read more about Pass-through Copy. |
htmlOutputSuffix |
-o |
String |
N/A | If the input and output directory match, index.html files will have this suffix added to their output filename to prevent overwriting the template. |
filters |
{} |
Object |
N/A | Filters can transform output on a template. Take the format function(str, outputPath) { return str; }. For example, use a filter to format an HTML file with proper whitespace. |
If you expose your config as a function instead of an object, we’ll pass in a config argument that you can use!
module.exports = function(config) {
return {
dir: {
input: "views"
}
};
};
This allows you to customize your template engines by using the Config helper methods.
Read more about eleventy-provided universal filters.
module.exports = function(eleventyConfig) {
// Liquid
eleventyConfig.addLiquidTag(name, function(tagToken, remainingTokens) {}, function(scope, hash) { … });
eleventyConfig.addLiquidFilter(name, function(value) { … });
// Nunjucks
eleventyConfig.addNunjucksFilter(name, function(value) { … });
// Handlebars
eleventyConfig.addHandlebarsHelper(name, function(value) { … });
// Universal filters (Experimental! Adds to Liquid, Nunjucks, and Handlebars)
eleventyConfig.addFilter(name, function(value) {});
return {};
};
Read more about this on the Collections documentation: Advanced Custom Filtering and Sorting.
Here are the features tested with each template engine that use external files and thus are subject to setup and scaffolding.
| Engine | Feature | Syntax |
|---|---|---|
| ejs | âś… Include (Preprocessor Directive) | <% include /user/show %> looks for _includes/show/user.ejs |
| ejs | âś… Include (pass in Data) | <%- include('/user/show', {user: 'Ava'}) %> looks for _includes/user/show.ejs |
| Liquid | âś… Include | {% include 'show/user' %} looks for _includes/show/user.liquid |
| Liquid | âś… Include (pass in Data) | {% include 'user' with 'Ava' %} |
| Liquid | âś… Include (pass in Data) | {% include 'user', user1: 'Ava', user2: 'Bill' %} |
| Liquid | âś… Custom Filters | `{{ name |
| Liquid | âś… Custom Tags | {% upper name %} (see config.addLiquidTag documentation) |
| Mustache | âś… Partials | {{> user}} looks for _includes/user.mustache |
| Handlebars | âś… Partials | {{> user}} looks for _includes/user.hbs |
| Handlebars | âś… Helpers | See handlebarsHelpers configuration option. |
| HAML | ❌ but 🔜 Filters | |
| Pug | âś… Includes | include /includedvar.pug looks in _includes/includedvar.pug |
| Pug | âś… Excludes | extends /layout.pug looks in _includes/layout.pug |
| Nunjucks | âś… Includes | {% include 'included.njk' %} looks in _includes/included.njk |
| Nunjucks | âś… Extends | {% extends 'base.njk' %} looks in _includes/base.njk |
| Nunjucks | âś… Imports | {% import 'macros.njk' %} looks in _includes/macros.njk |
| Nunjucks | âś… Filters | See nunjucksFilters configuration option. |
- Build Status:
- Code Coverage Statistics
npm run test
- Jekyll (Ruby)
- Hugo (Go)
- Hexo (JavaScript)
- Gatsby (JavaScript using React)
- Nuxt (JavaScript using Vue)
- More at staticgen.com
- Pagination
- Tagging of content
- Extensibility with system-wide content mapping IN PROGRESS
- Components system for development reusability
- Plugin system