grunt-render-nunjucks

Compile nunjucks-templates to static files

Getting Started

This plugin requires Grunt ~0.4.0 and node >=4.0.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-render-nunjucks --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-render-nunjucks');

The "renderNunjucks" task

Overview

In your project's Gruntfile, add a section named renderNunjucks to the data object passed into grunt.initConfig().

grunt.initConfig({
    renderNunjucks: {
        options: {
            //Task-specific options go here.
        },
        targetName: {
            options: {
                //Target-specific options go here.
            },
            files: {
                //Target-specific file list
            }
        }
    }
});

Usage Examples

Minimal Options

grunt.initConfig({
    renderNunjucks: {
        targetName: {
            files: [
                {
                    expand: true,
                    cwd: 'src/views/templates',
                    src: ['**/*.*'],
                    dest: 'build'
                }
            ]
        }
    }
});

Custom Options

grunt.initConfig({
    renderNunjucks: {
        options: {
            layoutDir: 'src/views/layouts',
            partialDir: 'src/views/partials'
        },
        dist: {
            options: {
                data: 'src/data.json',
                configureRenderer: function(env) {
                    env.addGlobal('currentYear', (new Date()).getFullYear());
                }
            },
            files: [
                {
                    expand: true,
                    cwd: 'src/views/templates',
                    src: ['**/*.*'],
                    dest: 'build'
                }
            ]
        }
    }
});

Options

options.data

Type: Object Default value: {}

This configures the data that will be available in the template. It is possible to pass an object, a JSON-file, a YAML-file or a function that can be asynchronous.

data: {}, //object
data: 'data.json', //JSON
data: 'data.yml', //YAML
data: function(resolve, reject) {
    resolve({});
}

options.layoutDir

Type: String Default value: false

This configures the relative path of the layout templates. e.g. src/views/layouts

If this value is set a filter will be available in the templates to load layouts from the configured directory.

{% extends "default.html" | layout %}

options.partialDir

Type: String Default value: false

This configures the relative path of the partial templates. e.g. src/views/partials

If this value is set a filter will be available in the templates to load partials from the configured directory:

{% include "item.html" | partial %}

options.baseDir

Type: String Default value: process.cwd()

This configures the absolute path of your project. It is used for the layout and partial filter.

options.noCache

Type Boolean Default value: false

If this option is true the cache-hashes will be ignored and all templates will be written to the file system.

Can be set with a flag: grunt renderNunjucks:targetName:no-cache

options.cacheFile

Type: String Default value: path.dirname(__dirname) + '/cache.json'

This configures the file the cached hashes are written into. The default is inside the grunt-render-nunjucks directory.

options.configureRenderer

Type: Function Default value: false

This function exposes the nunjucks render environment for configuration.

configureRenderer: function(env) {
    env.addGlobal('currentYear', (new Date()).getFullYear());

    env.addFilter('shorten', function(str, count) {
        return str.slice(0, count || 5);
    });
}

options.removeTrailingWhitespace

Type: Boolean Default value: true

This beautifies the output by removing trailing white spaces.

options.removeEmptyLines

Type: Boolean Default value: 'multiple'

This beautifies the output by removing empty lines. A special case is the value multiple. This value merges multiple empty lines into one.

options.data - pages

A special property in the options.data is the pages property. If the path of the rendered template matches with a key in the pages object, the values will be merged into the data that is available in the template.

data: {
    title: "Title",
    pages: {
        "test.html": {
            title: "Test - Title"
        }
    }
}

In this example the title will be Title in all templates, except in the test.html file, where it is overwritten with Test - Title.

If the files are configured as a dynamic files object, the cwd path will be removed from the path that is matched with the key in the pages object.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.