gulp-nunjucks-render

Render Nunjucks templates

Issues with the output should be reported on the Nunjucks issue tracker.

Install

Install with npm

npm install --save-dev gulp-nunjucks-render

Example

1var gulp = require('gulp');
2var nunjucksRender = require('gulp-nunjucks-render');
3
4gulp.task('default', function () {
5  return gulp.src('src/templates/*.html')
6    .pipe(nunjucksRender({
7      path: ['src/templates/'] // String or Array
8    }))
9    .pipe(gulp.dest('dist'));
10});

Example with gulp data

1var gulp = require('gulp');
2var nunjucksRender = require('gulp-nunjucks-render');
3var data = require('gulp-data');
4
5function getDataForFile(file) {
6  return {
7    example: 'data loaded for ' + file.relative
8  };
9}
10
11gulp.task('default', function () {
12	return gulp.src('src/templates/*.html')
13    .pipe(data(getDataForFile))
14    .pipe(nunjucksRender({
15      path: 'src/templates'
16    }))
17    .pipe(gulp.dest('dist'));
18});

API

Options

Plugin accepts options object, which contain these by default:

1var defaults = {
2  path: '.',
3  ext: '.html',
4  data: {},
5  inheritExtension: false,
6  envOptions: {
7    watch: false
8  },
9  manageEnv: null,
10  loaders: null
11};

• path - Relative path to templates
• ext - Extension for compiled templates, pass null or empty string if yo don't want any extension
• data - Data passed to template
• inheritExtension - If true, uses same extension that is used for template
• envOptions - These are options provided for nunjucks Environment. More info here.
• manageEnv - Hook for managing environment before compilation. Useful for adding custom filters, globals, etc. Example below
• loaders - If provided, uses that as first parameter to Environment constructor. Otherwise, uses provided path. More info here

For more info about nunjucks functionality, check https://mozilla.github.io/nunjucks/api.html and also a source code of this plugin.

Data

U can pass data as option, or you can use gulp-data like in example above.

1nunjucksRender({data: {
2  css_path: 'http://company.com/css/'
3}});

For the following template

1<link rel="stylesheet" href="{{ css_path }}test.css" />

Would render

1<link rel="stylesheet" href="http://company.com/css/test.css" />

Environment

If you want to manage environment (add custom filters or globals), you can to that with manageEnv function hook:

1var manageEnvironment = function(environment) {
2  environment.addFilter('slug', function(str) {
3    return str && str.replace(/\s/g, '-', str).toLowerCase();
4  });
5
6  environment.addGlobal('globalTitle', 'My global title')
7}
8
9nunjucksRender({
10  manageEnv: manageEnvironment
11}):

After adding that, you can use them in template like this:

1<h1>{{ globalTitle }}</h1>
2<h3>{{ 'My important post'|slug }}</h3>

And get this result:

1<h1>My global title</h1>
2<h3>my-important-post</h3>

License

MIT © Carlos G. Limardo and Kristijan Husak

Shout-outs

Sindre Sorhus who wrote the original gulp-nunjucks for precompiling Nunjucks templates. I updated his to render instead of precompile.

kristijanhusak for bug fixes and help with maintenance.