Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Static site generator for Node.js, Grunt.js, and Yeoman and Gulp. Render templates with Handlebars, Lo-Dash or any template engine. Used by Zurb Foundation, Zurb Ink, Less.js /, Topcoat, Web Experience Toolkit, and hundreds of other projects to build sites, themes, components, documentation, blogs and gh-pages.
JavaScript Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

Assemble v0.4.0 Build Status

Assemble makes it dead simple to build modular sites and components from reusable templates and data.

We love contributors, pull requests are welcome and followers are appreciated.


Visit the assemble-examples repo to see a list of example projects, such as:

Table of Contents

Getting started

It amazes me how flexible this whole system is, as we can dance around all the issues quite easily.

Thanks guys, this just goes to show how powerful assemble [is], I was expecting a short "no sorry, not possible",
but instead I've got multiple solutions.

If you're having trouble getting started, please create an Issue, we're happy to help.

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

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


The "assemble" task

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

  assemble: {
    options: {
      // Task-specific options go here.
    your_target: {
      // Target-specific file lists and/or options go here.

grunt.registerTask('default', [

Task targets, files and options may be specified according to the grunt Configuring tasks guide.


See the Options section on the Wiki for more information.


Type: String Default: undefined

Used with the {{assets}} variable to resolve the relative path from the dest file to the assets folder.


Type: Object|Array Default: src/data

Retrieves data from any specified JSON and/or YAML files to populate the templates when rendered. Data gets passed through the data object to the options on the assemble task, then to the context in your templates.

Also useful for specifying configuration data, such as when to render certain templates. For example:

Also see: YAML front matter


Type: String Default: undefined

If set, this defines the layout file to use for the task or target. However, when specifying a layout, unlike Jekyll, Assemble requires a file extension since you are not limited to using a single file type.


Type: Object|Array Default: undefined

Specifies the Handlebars partials files, or paths to the directories of files to be used.


Type: Object|Array Default: helper-lib

Path defined to a directory of custom helpers to use with the specified template engine. Assemble currently includes more than 100+ built-in Handlebars helpers, since Handlebars is the default engine for Assemble.


Type: Object|Array Default: helper-lib

Path defined to a directory of custom helpers to use with the specified template engine. Assemble currently includes more than 100+ built-in Handlebars helpers, since Handlebars is the default engine for Assemble.


Type: String Default: .html

Specify the file extension for destination files. Example:

More info about ext.


Type: Boolean Default: false

Remove anything after (and including) the first "." in the destination path, then append this value. In other words, when files are generated from different source folders this "flattens" them into the same destination directory. See [building the files object dynamically][files-object] for more information on files formats.

Custom "Options Variables"

You can add any custom variables directly to the options block:

assemble {
  myProject: {
    options: {
      custom_option1: 'value',
      custom_option2: 'value'
    files: {
      'dest': ['src/templates*.hbs']

This offers a great deal of flexibility, but it's also something that should be done sparingly because your tasks and targets can get out of hand pretty quickly.

Usage Examples

Here are a couple of common use cases for custom options variables:

development stages

Add custom variables for development stages, such as dev and prod:

assemble {
  myProject: {
    options: {
      dev: true,
      prod: false
    files: {
      'dest': ['src/templates*.hbs']

Then we can wrap sections in our templates with these contexts to include or exclude content based on truthy or falsy evalution of the dev and prod variables.

  <script src="script.js"></script>
  <script src="script.min.js"></script>

version consistency

Get or set metadata to/from package.json:

pkg: grunt.file.readJSON('package.json'),

assemble {
  myProject: {
    options: {
      version: '<%= pkg.version %>'
    files: {
      'dest': ['src/templates*.hbs']

Used in our templates like this: {{version}}

NOTE: It's worth noting that you can accomplish the same end goal by using the object instead of creating a custom "options variable". See the page in the wiki for more detail.

Task Examples

Visit the assemble-examples repo to see a list of example projects.

Compile Handlebars templates

Simple example of using data files in both .json and .yml format to build Handlebars templates.

assemble: {
  docs: {
    options: {
      data: 'src/data/**/*.{json,yml}'
    files: {
      'dist/': ['src/templates/**/*.hbs']

Generate a markdown README

The example shows how you can use Assemble to generate a markdown formatted readme from Handlebars templates.

assemble: {
  readme: {
    options: {
      flatten: true,
      partials: 'src/content/*.hbs',
      data: 'package.json',
      ext: ''
    src:  'src/templates/',
    dest: './'

Visit the assemble-examples-readme repo to see a working example.

Generate .xml sitemap

You can generate a sitemap from a static data source, such as sitemap.json, or use Assemble's built-in pages and page variables to automatically generate a sitemap from all pages in a target.

assemble: {
  options: {
    flatten: true,
    data: 'src/sitemap.json',
    ext: '.xml'
  component: {
    files: {
      'Sitemap.xml': ['src/sitemap.hbs']


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


Jon Schlinkert

Brian Woodward

Copyright and license

Copyright 2013 Assemble

MIT License

Release History

  • 2013-06-20 v0.4.0 New option "layoutdir" for defining the directory to be used for layouts. If layoutdir is defined, then layouts may be defined using only the name of the layout.
  • 2013-06-10 v0.3.81 Adding additional ways to load custom helpers. Now it's possible to use a glob pattern that points to a list of scripts with helpers to load. Adding examples and tests on how to use the new custom helper loading methods.
  • 2013-06-01 v0.3.80 Fixing bug with null value in engine
  • 2013-05-07 v0.3.77 Updated README with info about assemble methods
  • 2013-04-28 v0.3.74 Updating the assemble library to use the assemble-utils repo and unnecessary code.
  • 2013-04-21 v0.3.73 Fixing how the relative path helper worked and showing an example in the footer of the layout. This example is hidden, but can be seen by doing view source.
  • 2013-04-20 v0.3.72 Fixing the layout override issue happening in the page yaml headers. Something was missed during refactoring.
  • 2013-04-19 v0.3.9 Adding tags and categories to the root context and ensure that the current page context values don't override the root context values.
  • 2013-04-18 v0.3.8 Updating to use actual assets property from current page.
  • 2013-04-17 v0.3.7 Cleaning up some unused folders and tests
  • 2013-04-16 v0.3.6 Fixed missing assets property.
  • 2013-04-16 v0.3.5 Adding a sections array to the template engine so it can be used in helpers.
  • 2013-04-11 v0.3.4 More tests for helpers and global variables, organized tests. A number of bug fixes.
  • 2013-04-06 v0.3.3 helper-lib properly externalized and wired up. Global variables for filename, ext and pages
  • 2013-03-22 v0.3.22 Merged global and target level options so data and partial files can be joined
  • 2013-03-22 v0.3.21 Valid YAML now allowed in object (along with JSON)
  • 2013-03-18 v0.3.14 new relative helper for resolving relative paths

This file was generated using Grunt and assemble on Sun Jun 23 2013 10:04:02.

Something went wrong with that request. Please try again.