0.3.0 • Public • Published


    Grunt task for generating static pages from templated partials.

    Getting Started

    This plugin requires Grunt ~0.4.5

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

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


    The "flats" task


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

      flats: {
        build: {
          options: {
            basePath: '_templates',
            layoutPath: 'layouts',
            partialPath: 'partials',
            masterSrc: 'masterpage/master.html',
            destPath: '_templates'



    Type: String Default value: '_templates'

    Working path for all templating, relative to root


    Type: String Default value: 'layouts'

    Directory where individual layouts are kept, relative to basePath


    Type: String Default value: 'partials'

    Directory where individual partials are kept, relative to basePath


    Type: String Default value: 'masterpage/master.html'

    Path to masterpage, relative to basePath


    Type: String Default value: '_templates'

    Directory where individual layouts are compiled to, same as basePath by default

    Note: Grunt-flats includes grunt-contrib-clean as a dependency, and will clean all *.html files from this directory on build (excluding masterSrc, should you want to keep that in the basePath directory).

    File structure

    Grunt-flats attempts to be as flexible as possible. The file structure based off the tasks' default options would follow:

        (individual layout templates)
        (partials and/or user-defined sub-directories)
      (compiled templates)

    However, each of these directories and paths are configurable to match your existing workflow. If you're a fan of Pattern Lab's Atomic Design Patterns or Lonely Planet's Rizzo Styleguide you can folderize your partials accordingly.

    The grunt-flats Git repo contains an example _templates directory. This includes a master, layouts and partials to demonstrate how the plugin could be utilised.

    It is especially effective when wanting to produce a living styleguide for a site; ensuring all code snippets are maintained in a single place and any changes are automatically propogated through all templates.

    Master page

    See: /_templates/masterpage/master.html

    The master should contain all of your site-wide template markup. It contains a single {{>content}} partial to act as a placeholder; this is where each individual layout's markup will be rendered.

    Partials/include pattern

    Grunt-flats uses Hogan.js under the hood. It's built against Mustache's test suite, so you can easily port your existing Mustache or Handlebars templates and retain the same partial syntax.

    To include a partial, reference it using an extensionless path. This should be relative to the options.partialPath directory. E.g.


    Partials are constructed recursively, so can be infinitely nestable.

    Partial-specific data

    Partial rendering can be enhanced by including a partial-specific data object. This syntax is similar to that utilised by Pattern Lab:

    {{>components/module-promo ("imgsrc": "/images/new-promo.jpg", "title": "New Module Title")}}

    Partial data is wrapped within parenthesis ( ... ) and appended to the partial reference. Within, the data should be formatted as you would any standard JSON object. Keys and values are wrapped in double quotes, and each key/value pair separated by a single comma.

    Partial default values

    Once a data object has been defined and passed to a partial, we can utilise these values on their own, or pair them with defaults. Use Mustache's Inverted Sections syntax to declare a default value to use, following a standard Mustache Variable. For example, within components/module-promo:

    <img src="{{imgsrc}}{{^imgsrc}}/images/default-promo-image.jpg{{/imgsrc}}" alt="Placeholder" />
    <h2>{{title}}{{^title}}Default Module Title{{/title}}</h2>

    This way we can define default dummy data for any partials throughout the templates, and be sure only one value will be rendered. It allows our partials to be more customisable and re-usable, in a very targetted way.


    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.

    Release History

    • v0.1.0 Initial setup, non-recursive partial rendering
    • v0.2.0 Rewrite to support infinitely nestable partial rendering
    • v0.2.1 Added error checking for incorrect/missing partials
    • v0.3.0 Added partial-specific data rendering


    npm i grunt-flats

    DownloadsWeekly Downloads






    Last publish


    • adamduncan