matthewwithanm / grunt-jinja

A grunt plugin for compiling Jinja2 templates with James Long's nunjucks templating system

grunt-jinja

A grunt plugin for compiling Jinja2 templates with James Long's awesome nunjucks templating system.

Getting Started

This plugin requires Grunt ~0.4.1

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-jinja --save-dev

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

grunt.loadNpmTasks('grunt-jinja');

The "jinja" task

Overview

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

grunt.initConfig({
  jinja: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Options

options.templateDirs

Type: Array Default value: [path.join(process.cwd(), 'templates')]

A an array of paths in which your templates can be found. If not provided, this will default to the "templates" directory at the same level as your Gruntfile.

options.contextRoot

Type: String Default value: path.join(process.cwd(), 'template-context')

The directory in which your template context files can be found. grunt-jinja will look in this directory to find JSON documents or node modules that correspond to your template names and use them for that template. For example, if you use a template "products/phones.html", you can create a "products/phones.json" or "products/phones.js" file in the context root and it will be used as context when rendering the template. To add context to all of your templates, create an "_all.json" or "_all.js" file in the context root.

options.filters

Type: Object Default value: {}

An object whose keys are filter names and values are functions. Each pair will be registered with the template environment using the addFilter method.

Other options

Other options are passed directly to the nunjucks environment object. Currently, valid options are as follows:

options.dev

Type: Boolean Default value: false

A boolean which, if true, puts nunjucks into development mode which means that error stack traces will not be cleaned up.

options.autoescape

Type: Boolean Default value: true

A boolean which, if true, will escape all output by default See Autoescaping.

options.tags

Type: Object Default value: {}

An object specifying custom block start and end tags. See Customizing Variable and Block Tags.

Usage Examples

Default Options

In this example, the default options are used to compile a templates in the "templates/" directory to the "built" directory:

grunt.initConfig({
  jinja: {
    files: {
      'built/index.html': 'templates/index.html'
    },
  },
})

This example compiles all templates that don't begin with an underscore:

grunt.initConfig({
  jinja: {
    dist: {
      files: [{
        expand: true,
        dest: 'built/',
        cwd: 'templates/',
        src: ['**/!(_)*.html']
      }]
    }
  }
})

Custom Options

In this example, custom options are used to load the templates from directories other than "templates":

grunt.initConfig({
  jinja: {
    dist: {
      options: {
        templateDirs: ['src/templates']
      },
      files: {
        'built/index.html': 'src/templates/index.html'
      }
    }
  }
})

grunt-jinja's Issues

using require to load context prevents ability to use in watch

In the loadContext function, require is used to load the js or json file. require will only load the file once. In our build we run grunt-jinja during a watch statement so it can be executed multiple times without being reloaded. require should be replaced with a call to fs.readFile

    loadContext = (templateName, removeExtension = true) ->
      ext = path.extname(templateName)
      contextName = if ext then templateName[...-ext.length] else templateName
      try
        context = require path.resolve(options.contextRoot, contextName)
      catch err
        return {}
      grunt.log.writeln "Using context #{ contextName }"
      context

Upgrade to latest nunjucks

Ability to pass arbitrary json file in as config

It's a bit onerous to require the json file be named so specifically (either template.json or the same name as the template). I have multiple templates that I'd like to have access to a central json file that cannot be placed in the contextDir for various reasons. Is this possible?

All contextRoot filename.

Hi @matthewwithanm I was trying to set up a single JSON as the context for all my templates, and created an all.json file as directed. However, the templates were not picking up the context. I did some poking around and it looks like the grunt task calls loadContext('_all'). I changed the filename to _all.json and voila!

Thanks for writing this task, good stuff!