11ty

Eleventy Documentation

Documentation Pages

Nunjucks

Template Languages:

Eleventy Short NameFile ExtensionNPM Package
njk.njknunjucks

You can override a .njk file’s template engine. Read more at Changing a Template’s Rendering Engine.

Nunjucks Options

Optional: Use your Nunjucks Environment

As an escape mechanism for advanced usage, pass in your own instance of a Nunjucks Environment using the Configuration API.

let Nunjucks = require("nunjucks");

module.exports = function(eleventyConfig) {
let nunjucksEnvironment = new Nunjucks.Environment(
new Nunjucks.FileSystemLoader("_includes")
);

eleventyConfig.setLibrary("njk", nunjucksEnvironment);
};

Supported Features

FeatureSyntax
✅ Includes{% include 'included.njk' %} looks in _includes/included.njk (does not process front matter)
✅ Extends{% extends 'base.njk' %} looks in _includes/base.njk (does not process front matter)
✅ Imports{% import 'macros.njk' %} looks in _includes/macros.njk (does not process front matter)
✅ Filters{% name | filterName %} Read more about Filters.
Eleventy Universal Filters{% name | filterName %} Read more about Filters.
Custom Tags{% uppercase name %} Read more about Custom Tags. New in v0.5.0
Shortcodes{% uppercase name %} Read more about Shortcodes. New in v0.5.0

Filters

Filters are used to transform or modify content. You can add Nunjucks specific filters, but you probably want to add a Universal filter instead.

Read more about Nunjucks Filter syntax.

module.exports = function(eleventyConfig) {
// Nunjucks Filter
eleventyConfig.addNunjucksFilter("myNjkFilter", function(value) {});

// Nunjucks Asynchronous Filter (read on below)
eleventyConfig.addNunjucksAsyncFilter("myAsyncNjkFilter", function(value, callback) {});

// Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
eleventyConfig.addFilter("myFilter", function(value) {});
};

Usage

<h1>{{ myVariable | myFilter }}</h1>

Asynchronous Nunjucks Filters

By default, almost all templating engines are synchronous. Nunjucks supports some asynchronous behavior, like filters. Here’s how that works:

module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksAsyncFilter("myAsyncFilter", function(value, callback) {
setTimeout(function() {
callback(null, "My Result");
}, 100);
});
};

The last argument here is the callback function, the first argument of which is the error object and the second is the result data. Use this filter like you would any other: {{ myValue | myAsyncFilter }}.

Here’s a Nunjucks example with 2 arguments:

module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksAsyncFilter("myAsyncFilter", function(value1, value2, callback) {
setTimeout(function() {
callback(null, "My Result");
}, 100);
});
};

Multi-argument filters in Nunjucks are called like this: {{ myValue1 | myAsyncFilter(myValue2) }}.

Shortcodes

Shortcodes are basically reusable bits of content. You can add Nunjucks specific shortcodes, but you probably want to add a Universal shortcode instead.

Single Shortcode

module.exports = function(eleventyConfig) {
// Nunjucks Shortcode
eleventyConfig.addNunjucksShortcode("user", function(name, twitterUsername) {});

// Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`
;

});
};

Usage

{% user "Zach Leatherman", "zachleat" %}

Outputs

<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>>
</div>

Paired Shortcode

module.exports = function(eleventyConfig) {
// Nunjucks Shortcode
eleventyConfig.addPairedNunjucksShortcode("user", function(bioContent, name, twitterUsername) {});

// Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`
;

});
};

Usage

Note that you can put any Nunjucks tags or content inside the {% user %} shortcode! Yes, even other shortcodes!

{% user "Zach Leatherman", "zachleat" %}
Zach likes to take long walks on Nebraska beaches.
{% enduser %}
Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>

Shortcode Named Argument Syntax (Nunjucks-only)

Creates a single argument object to pass to the shortcode.

module.exports = function(eleventyConfig) {
// Nunjucks Shortcode
eleventyConfig.addNunjucksShortcode("user", function(user) {
return `<div class="user">
<div class="user_name">${user.name}</div>
${user.twitter ? `<div class="user_twitter">@${user.twitter}</div>`
: ''}

</div>`;
});
};

Usage

The order of the arguments doesn’t matter.

{% user name="Zach Leatherman", twitter="zachleat" %}
{% user twitter="zachleat", name="Zach Leatherman" %}
Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
</div>

Usage

Importantly, this syntax means that any of the arguments can be optional (without having to pass in a bunch of null, null, null to maintain order).

{% user name="Zach Leatherman" %}
Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
</div>

Related Docs