Lots of projects such as blogs and documentation only require static content. To quickly and easily produce this kind of content we can use a static site generator. There are many different generators to choose from - over 300 listed here.

It makes sense to stay in familiar territory so I prefer working in the JavaScript ecosystem. This means we don’t have to shoehorn it into our workflow and can still use handlebars, sass, gulp/grunt etc.

Assemble

I have found Assemble to be my favourite. It does require some setup opposed to something more cookie cutter like Wintersmith. The flexibility it provides however makes for a much more powerful tool.

Recommendations

To hopefully save you some headaches I would like to point out:

• Use grunt

Assemble is built as a grunt plugin. Currently the gulp alternative is only in alpha. If you need to use gulp I would recommend using gulp-grunt.

• Remember that it is just JavaScript

If you can’t get something to work then you can write it yourself. For example if you don’t know how to import that file into assemble correctly then just use node. You can always refactor it later on.

Cheat Sheet

Using Handlebars

The full documentation is here. I would like to highlight some points that weren’t instantly obvious to me:

Working with Objects

{{#each object}}
    {{@key}}: {{this}}
{{/each}}

Working with Arrays

{{#each array}}
    {{@index}}: {{this}}
{{/each}}

Creating Helpers

module.exports.register = function(Handlebars, options) {
    'use strict';

    Handlebars.registerHelper(’example', function(param) {
        return param + ‘!’;
    });
}

Using Helper

{{{example “onetwo"}}}

Creating HTML from Markdown

This is the standard use case for assemble for example generating blog posts with content written in markdown.

grunt.initConfig({
    assemble: {
      options: {
        flatten: true,
        layoutdir: 'templates/layouts',
        partials: 'templates/partials/*.hbs',
        helpers: 'templates/helpers/*.js',
      },
      markdown: {
        options: {
          ext: '.html',
          engine: 'handlebars',
        },
        files: {
          'public/': ['contents/**/*.md']
        }
      }
    }
});

Creating HTML from JSON

We have a JSON file and we want to generate some HTML for example list of posts or table of contents.

Instead of having to scaffold the JSON from the files individually we can use markdown2json to build up our JSON.

m2j: {
    release: {
        options: {
            minify: false,
            width: 60
        },
        files: {
            'templates/data/example.json': ['contents/example/*.md']
        },
    }
}

Then we can pass this JSON into assemble to produce the pages:

grunt.initConfig({
    assemble: {
      options: {
        flatten: true,
        layoutdir: 'templates/layouts',
        partials: 'templates/partials/*.hbs',
        helpers: 'templates/helpers/*.js',
      },
      blog: {
        options: {
          engine: 'handlebars',
          layout: ‘layout.hbs',
          pages: grunt.file.readJSON('templates/data/example.json')
        },
        files: { 'public/': ['src/index.hbs'] }
      }
    }
});

I have shared the sketch file I made for this article’s pattern here.