Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including eleventy-cli with all npm packages installed. Try it out:

var eleventyCli = require("eleventy-cli")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

eleventy-cli v0.1.9

Transform a directory of templates into HTML.

eleventy 🕚

A static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.

Works with:

Getting Started

Installation

Available on npm.

npm install -g eleventy-cli

Sample project

Have a look at @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.

Usage

# Searches the current directory, outputs to ./_site
eleventy

# Equivalent to
eleventy --input=. --output=_site

# Automatically run when template files change.
eleventy --watch

# 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

Examples

Example: Default options

eleventy --input=. --output=_site

A template.md in the current directory will be rendered to _site/template/index.html. Read more about Permalinks

Example: Same Input and Output

Yes, you can use the same input and output directories, like so:

# Watch a directory for any changes to markdown files, then
# automatically parse and output as HTML files, respecting
# directory structure.

eleventy --input=. --output=. --watch --formats=md
Exception: index.html Templates

When the input and output directories are the same and the source template is named index.html, it will output as index-o.html to avoid overwriting itself. This is a special case that only applies to index.html filenames. You can customize the -o suffix with the htmlOutputSuffix configuration option.

# Adds `-o` to index.html file names to avoid overwriting matching files.

eleventy --input=. --output=. --formats=html

Data (optional)

Front Matter on any Template

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 _includes folder.
  • pagination: Enable to iterate over data. Output multiple HTML files from a single template. Read more about Pagination.

Special Variables

Data Files

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.

Ignore files (optional)

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.

Configuration (optional)

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 KeyDefault OptionValid OptionsCommand Line OverrideDescription
dir.input.Any valid directory.--inputControls the top level directory inside which the templates should be found.
dir.includes_includesAny valid directory inside of dir.input.N/AControls the directory inside which the template includes/extends/partials/etc can be found.
dir.data_dataAny valid directory inside of dir.input.N/AControls the directory inside which the global data template files, available to all templates, can be found.
dir.output_siteAny valid directory.--outputControls the directory inside which the transformed finished templates can be found.
dataTemplateEngineliquidA valid template engine or falseN/ARun the data.dir global data files through this template engine before transforming it to JSON.
markdownTemplateEngineliquidA valid template engine or falseN/ARun markdown through this template engine before transforming it to HTML.
htmlTemplateEngineliquidA valid template engine or falseN/ARun HTML templates through this template engine before transforming it to (better) HTML.
templateFormatsliquid,ejs, md,hbs, mustache,haml, pug,njk,htmlAny combination of these--formatsSpecify which type of templates should be transformed.
htmlOutputSuffix-oStringN/AIf the input and output directory match, index.html files will have this suffix added to their output filename to prevent overwriting the template.
filters{}ObjectN/AFilters 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.
handlebarsHelpers{}ObjectN/AThe helper functions passed to Handlebars.registerHelper. Helper names are keys, functions are the values.
nunjucksFilters{}ObjectN/AThe helper functions passed to nunjucksEnv.addFilter. Helper names are keys, functions are the values.

Template Engine Features

Here are the features tested with each template engine that use external files and thus are subject to setup and scaffolding.

EngineFeatureSyntax
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' %}
Mustache✅ Partials{{> user}} looks for _includes/user.mustache
Handlebars✅ Partials{{> user}} looks for _includes/user.hbs
Handlebars✅ HelpersSee handlebarsHelpers configuration option.
HAML❌ but 🔜 Filters
Pug✅ Includesinclude /includedvar.pug looks in _includes/includedvar.pug
Pug✅ Excludesextends /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✅ FiltersSee nunjucksFilters configuration option.

Tests

Build Status: Build Status

npm run test
npm run watch:test

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free