Stand with Ukraine 🇺🇦
Eleventy
The possum is Eleventy’s mascot

Eleventy Documentation

This is an older version of Eleventy. Go to the newest Eleventy docs (current path: /docs/languages/javascript/) or the full release history.
Menu

JavaScript

Template Languages:

Eleventy Short NameFile ExtensionNPM Package
11ty.js.11ty.jsN/A

Eleventy supports many different types of JavaScript content that will be parsed as Eleventy templates:

Raw Values #

Raw values will not have access to Data or JavaScript Template Functions. Use a function that returns a value instead.

String #

Syntax JavaScript
module.exports = "<p>Zach</p>";

Or template literals:

Syntax JavaScript
module.exports = `<p>These can
span
multiple
lines!</p>
`
;

Buffer #

Some templating libraries return Buffers (e.g. viperHTML).

Syntax JavaScript
module.exports = Buffer.from("<p>Zách</p>");

Promise #

Syntax JavaScript
module.exports = new Promise((resolve, reject) => {
setTimeout(function() {
resolve("<p>Zach</p>");
}, 1000);
});

Function #

Can return any raw value (e.g. String, Buffer, Promise). Use template literals to embed data values without having to concatenate strings!

Syntax JavaScript
module.exports = function(data) {
return `<p>${data.name}</p>`;
};

De-structuring syntax is a little bit easier to read:

Syntax JavaScript
module.exports = function({name}) {
return `<p>${name}</p>`;
};

Maybe you like arrow functions:

Syntax JavaScript
module.exports = ({name}) => `<p>${name}</p>`;

async functions work too:

Syntax JavaScript
const getAnAsyncThing = require("./lib/asyncThing");

module.exports = async function(data) {
return `<p>${await getAnAsyncThing()}</p>`;
};

Classes #

Eleventy looks for classes that have a render method and uses render to return the content of the template. render methods can be async.

render can return any raw value (e.g. String, Buffer, Promise).

Syntax JavaScript
class Test {
// or `async render({name}) {`
render({name}) {
return `<p>${name}</p>`;
}
}

module.exports = Test;

Optional data Method #

YAML Front Matter is not supported in JavaScript template types. Use data methods instead!

This data acts as Front Matter for the template and similarly to Front Matter will take precedence over all other data in the data cascade. The data method can be asynchronous async data() or it can be a getter get data().

Syntax JavaScript
class Test {
// or `async data() {`
// or `get data() {`
data() {
return {
name: "Ted",
layout: "teds-rad-layout",
// … other front matter keys
};
}

render({name}) {
// will always be "Ted"
return `<p>${name}</p>`;
}
}

module.exports = Test;

The permalink data key will work here. Permalinks can be a raw value (e.g. String, Buffer, Promise) or a Function that returns any raw value.

Syntax JavaScript
class Test {
data() {
return {
// Writes to "/my-permalink/index.html"
permalink: "/my-permalink/"
};
}

render(data) { /* … */ }
}

module.exports = Test;

Permalink Functions can return any raw value (e.g. String, Buffer, Promise).

Syntax JavaScript
class Test {
data() {
return {
key: "hello",
// Writes to "/my-permalink/hello/index.html"
permalink: data => `/my-permalink/${data.key}/`
};
}

render(data) { /* … */ }
}

module.exports = Test;

Universal filters, shortcodes, and other JavaScript Template Functions work here and are exposed on this. Read more about Eleventy provided Universal Filters.

Syntax JavaScript
class Test {
data() {
return {
title: "This is my blog post title",
// Writes to "/this-is-my-blog-post-title/index.html"
permalink: function(data) {
return `/${this.slug(data.title)}/`;
}
};
}

render(data) { /* … */ }
}

module.exports = Test;

Markdown and JavaScript #

Yes, you can use JavaScript as your preprocessor language for Markdown. Read more about templateEngineOverride.

Syntax JavaScript and Markdown
class Test {
data() {
return {
myName: "Zach",
templateEngineOverride: "11ty.js,md"
};
}

render(data) {
return `# This is ${data.myName}`;
}
}

module.exports = Test;
While templateEngineOverride: 11ty.js,md works to add markdown support, the special behavior of JavaScript templates does not allow other template engines to be supported here (e.g. templateEngineOverride: njk,md). This will be mitigated with Enhancement Request Issue #148.

JavaScript Template Functions #

A JavaScript Template Function allows you to extend your JavaScript templates with extra functionality. If you add any Universal Filters or Shortcodes, they will be exposed as JavaScript Template Functions.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
eleventyConfig.addJavaScriptFunction("myFunction", function(a, b) {});
};
Filename js-fn-example.11ty.js
module.exports = function(data) {
return `<h1>${this.myFunction(data.a, data.b)}</h1>`;
};

Asynchronous JavaScript Template Functions #

This works the same as any async JavaScript function or function that returns a Promise.

This is the same as the example above but adds async before the function.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
eleventyConfig.addJavaScriptFunction("myAsyncFunction", async function(a, b) {});
};

This is the same as the example above but adds await before the function is called.

Filename js-async-fn-example.11ty.js
module.exports = async function(data) {
return `<h1>${await this.myAsyncFunction(data.a, data.b)}</h1>`;
};

Warning about Arrow Functions #

Note that by definition (read on MDN) arrow functions do not have access to this, so any use of JavaScript Functions inside of an arrow function template will throw an error.
Filename js-arrow-fn-example.11ty.js
module.exports = (data) => {
// Using `this` in an arrow function will throw an error!
return `<h1>${this.myFunction(data.a, data.b)}</h1>`;
};

Relationship to Filters and Shortcodes #

Any universal filters or shortcodes will also be available as JavaScript Template Functions.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Universal filters (Adds to Liquid, Nunjucks, 11ty.js, and Handlebars)
eleventyConfig.addFilter("myFilter", function(myVariable) {});

// Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
eleventyConfig.addShortcode("user", function(firstName, lastName) {});

// Universal Paired Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
eleventyConfig.addPairedShortcode("pairedUser", function(content, firstName, lastName) {});
};
Filename universal-examples.11ty.js
module.exports = function(data) {
return `
<h1>
${this.myFilter(data.myVar)}</h1>
<p>
${this.user(data.firstName, data.lastName)}</p>
<p>
${this.pairedUser(`Here is some more content`, data.firstName, data.lastName)}</p>
`
;
};

Access to page data values New in v0.11.0 #

If you aren’t using an arrow function, JavaScript Functions (and Nunjucks, Liquid, and Handlebars Shortcodes) will have access to Eleventy page data values without needing to pass them in as arguments.

module.exports = function(eleventyConfig) {
eleventyConfig.addJavaScriptFunction("myFunction", function() {
// Available in 0.11.0 and above
console.log( this.page );

// For example:
console.log( this.page.url );
console.log( this.page.inputPath );
console.log( this.page.fileSlug );
});
};

Other pages in Template Languages:


Related Docs