Nunjucks Documentation

You can include Nunjucks in the browser using a script tag or as an AMD module.

Choosing a build

• nunjucks.js: The full library (approx. 20K min/gzipped). Includes the full compiler, allowing you to dynamically load and compile templates on the fly. Recommended for development or if file size is not a priority.
• nunjucks-slim.js: The slim version (approx. 8K min/gzipped). Does not include the compiler and only works with precompiled templates. Recommended for production.

Loading methods

Script tag:

<script src="nunjucks.js"></script>

AMD module:

define(['nunjucks'], function(nunjucks) {
});

Filters are functions that operate on variables, invoked using the pipe operator (|). Filters can accept arguments and can be chained together to perform multiple transformations in sequence.

{{ foo | title }}
{{ foo | join(",") }}
{{ foo | replace("foo", "bar") | capitalize }}

Regular expressions can be created using the r prefix. They behave like JavaScript RegExp objects.

{% set regExp = r/^foo.*/g %}
{% if regExp.test('foo') %}
  Foo in the house!
{% endif %}

Nunjucks supports an inline if expression similar to JavaScript's ternary operator, which is useful for providing default values.

{{ "true" if foo else "false" }}
{{ baz(foo if foo else "default") }}

Variables are retrieved from the template context. You can display a variable using double curly braces {{ ... }}. You can access object properties using either dot notation or bracket notation, similar to JavaScript.

Note on null/undefined: If a variable's value is undefined or null, nothing will be rendered. This also applies to accessing properties of an undefined object (e.g., if foo is undefined, {{ foo.bar }} will not render).

{{ username }}
{{ foo.bar }}
{{ foo["bar"] }}

Install the Nunjucks templating engine using npm.

npm install nunjucks

Nunjucks supports keyword arguments (similar to Python) for functions, filters, and macros. When you use keyword arguments in a template, Nunjucks converts them into a single object passed as the last argument to the underlying JavaScript function.

Example of calling a function with keyword arguments:

{{ foo(1, 2, bar=3, baz=4) }}

Equivalent JavaScript call:

foo(1, 2, { bar: 3, baz: 4 });

You can also define macros with default values for keyword arguments. Nunjucks will automatically match the provided keyword arguments to the defined values.

Nunjucks supports JavaScript-like literals (Strings, Numbers, Arrays, Dicts, Booleans) and mathematical operators:

• Addition: +
• Subtraction: -
• Division: /
• Integer division: //
• Remainder: %
• Multiplication: *
• Power: **

Note: It is recommended to keep complex logic in your JavaScript code rather than in the template.

To use Nunjucks in a Node.js environment, install the package using npm. Once installed, you can access it using require('nunjucks').

$ npm install nunjucks

Nunjucks supports an inline if expression similar to JavaScript's ternary operator. The else part is optional.

Syntax: {{ value_if_true if condition else value_if_false }}

{{ "true" if foo else "false" }}
{{ baz(foo if foo else "default") }}
{{ "true" if foo }}