Nunjucks
Template Languages:
Eleventy Short Name | File Extension | NPM Package |
---|---|---|
njk |
.njk |
nunjucks |
You can override a .njk
file’s template engine. Read more at Changing a Template’s Rendering Engine.
Nunjucks Environment Options Jump to heading
We use Nunjucks defaults for all environment options (shown in the configure
section of the Nunjucks docs).
Optional: Use your Nunjucks Environment Options New in v1.0.0 Jump to heading
It’s recommended to use the Configuration API to override the default Nunjucks options.
module.exports = function(eleventyConfig) {
eleventyConfig.setNunjucksEnvironmentOptions({
throwOnUndefined: true,
autoescape: false, // warning: don’t do this!
});
};
Advanced: Use your Nunjucks Environment Jump to heading
While it is preferred and simpler to use the Options-specific API method above (new in Eleventy 1.0!)—as an escape mechanism for advanced usage you may pass in your own instance of a Nunjucks Environment using the Configuration API.
setNunjucksEnvironmentOptions
above—this method will override any configuration set there.let Nunjucks = require("nunjucks");
module.exports = function(eleventyConfig) {
let nunjucksEnvironment = new Nunjucks.Environment(
new Nunjucks.FileSystemLoader("_includes")
);
eleventyConfig.setLibrary("njk", nunjucksEnvironment);
};
Supported Features Jump to heading
Feature | Syntax |
---|---|
✅ Includes | {% include 'included.njk' %} looks in _includes/included.njk . Filenames must be in quotes. Does not process front matter in the include file. |
✅ Includes (Relative Path) | Relative paths use ./ (template’s directory) or ../ (template’s parent directory).Example: {% include './included.njk' %} looks for included.njk in the template’s current directory. Does not process front matter in the include file. |
✅ Extends | {% extends 'base.njk' %} looks in _includes/base.njk . Does not process front matter in the include file. |
✅ Extends (Relative Path) | Relative paths use ./ (template’s directory) or ../ (template’s parent directory)Example: {% extends './base.njk' %} looks for base.njk in the template’s current directory. Does not process front matter in the include file. |
✅ Imports | {% import 'macros.njk' %} looks in _includes/macros.njk . Does not process front matter in the include file. |
✅ Imports (Relative Path) | Relative paths use ./ (template’s directory) or ../ (template’s parent directory):{% import './macros.njk' %} looks for macros.njk in the template’s current directory. Does not process front matter in the include file. |
✅ 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. |
✅ Shortcodes | {% uppercase name %} Read more about Shortcodes. |
Filters Jump to heading
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 Jump to heading
<h1>{{ myVariable | myFilter }}</h1>
Multiple Filter Arguments Jump to heading
module.exports = function(eleventyConfig) {
// Nunjucks Filter
eleventyConfig.addNunjucksFilter("concatThreeStrings", function(arg1, arg2, arg3) {
return arg1 + arg2 + arg3;
});
};
<h1>{{ "first" | concatThreeThings("second", "third") }}</h1>
Asynchronous Nunjucks Filters Jump to heading
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 Jump to heading
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 Jump to heading
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 Jump to heading
{% user "Zach Leatherman", "zachleat" %}
Outputs Jump to heading
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>>
</div>
Paired Shortcode Jump to heading
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 Jump to heading
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) Jump to heading
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 Jump to heading
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 Jump to heading
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>
Asynchronous Shortcodes Jump to heading
Note that the configuration methods here to add asynchronous shortcodes are different than their synchronous counterparts.
module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksAsyncShortcode("user", async function(name, twitterUsername) {
return await fetchAThing();
});
eleventyConfig.addPairedNunjucksAsyncShortcode("user2", async function(content, name, twitterUsername) {
return await fetchAThing();
});
};
Usage Jump to heading
(It’s the same.)
{% user "Zach Leatherman", "zachleat" %}
{% user2 "Zach Leatherman", "zachleat" %}
Zach likes to take long walks on Nebraska beaches.
{% enduser2 %}
Access to page
data values New in v0.11.0
Jump to heading
If you aren’t using an arrow function, Nunjucks Shortcodes (and Handlebars, Liquid, and 11ty.js JavaScript Functions) will have access to Eleventy page
data values without needing to pass them in as arguments.
module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksShortcode("myShortcode", 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 );
});
};
Generic Global New in v1.0.0 Jump to heading
Nunjucks provides a custom way to add globals to templates. These can be any arbitrary JavaScript: functions, variables, etc. Note that this is not async-friendly (Nunjucks does not support await
inside of templates).
module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksGlobal("fortythree", 43);
};
{{ fortythree }}
module.exports = function(eleventyConfig) {
eleventyConfig.addNunjucksGlobal("fortytwo", function() {
return 42;
});
};
{{ fortytwo() }}
Read more on the Nunjucks documentation or relevant discussion on Eleventy Issue #1060.