gulp-nunjucks-api

Render Nunjucks templates with data, custom filters, custom context functions and options for other Nunjucks API features.

Install

Install with npm

npm install --save-dev gulp-nunjucks-api

Example

var gulp = require('gulp');
var nunjucksRender = require('gulp-nunjucks-api');

gulp.task('default', function () {
  return gulp.src('src/templates/*.html')
    .pipe(nunjucksRender({
		  src: 'src/templates',
      data: require('./global-data.json'),
      filters: require('./global-filters.js'),
      functions: require('./global-functions.js')
		}))
		.pipe(gulp.dest('dist'));
});

Example with gulp data

var gulp = require('gulp');
var nunjucksRender = require('gulp-nunjucks-api');
var data = require('gulp-data');

function getDataForFile(file){
  return {
    example: 'data loaded for ' + file.relative
  };
}

gulp.task('default', function () {
	return gulp.src('src/templates/*.html')
	  .pipe(data(getDataForFile))
		.pipe(nunjucksRender({
      src: 'src/templates/'
    }))
		.pipe(gulp.dest('dist'));
});

API

gulp-nunjucks-api(options)

Renders source templates using the given options to configure the Nunjucks API with custom data, extensions, filters and contextual functions.

Same options as nunjucks.configure():

• watch (default: false) reload templates when they are changed.
• express an express app that nunjucks should install to.
• autoescape (default: false) controls if output with dangerous characters are escaped automatically. See Autoescaping.
• tags (default: see nunjucks syntax) defines the syntax for nunjucks tags. See Customizing Syntax.

With the following additional options:

• extension (default: ".html") String. File extension to output. Pass 'inherit' to use the extension of the input file.
• src (default: undefined) String or Array. Search path(s) for nunjucks.configure().
• data (default: {}) Ojbect. Global data merged into the Nunjucks render context.
• errors (default: true) Boolean. Whether to emit errors to gulp or not. Set to false to let the gulp task continue on errors. See also: the verbose option.
• extensions (default: {}) Object. Global extensions added to the Nunjucks environment. See Custom Tags.
• filters (default: {}) Object. Global filter functions added to the Nunjucks environment. See Custom Filters.
• functions (default: {}) Object. Global functions merged into the Nunjucks render context.
• globals (default: undefined) Object. A single object which provides data, extensions, filters and functions objects instead of setting each of these options separately. The separate global options are merged into this base object.
• locals (default: undefined) Boolean or String. When true, enables loading of local template context data and functions from files that match the following default pattern: "<filename>.+(js|json)". When a glob pattern string is given, the directory containing a given template will be searched using the pattern. Data and functions from all matched files are merged into the render context. Note that the token <filename> will be replaced with a given template's file name including extension. Use the <filename_noext> token instead in a custom pattern to target the file name without extension.
• verbose (default: false) Boolean. When true, detailed operational data is logged to the console.

Render with data example

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

For the following template

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

Would render

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

Watch mode

Nunjucks' watch feature, which is normally enabled by default, is disabled by
default for gulp. Pass watch: true to enable it:

nunjucksRender({
  src: './source',
  watch: true
});

License

MIT © Devoptix LLC

Shout-outs

Carlos G. Limardo who wrote gulp-nunjucks-render which I am forking in order to update Nunjucks and do other stuff.

Sindre Sorhus who wrote the original gulp-nunjucks for precompiling Nunjucks templates.