Assemble is a powerful, extendable and easy to use static site generator for node.js. Used by thousands of projects for much more than building websites, Assemble is also used for creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, gh-pages and more! Assemble can also be used with gulp and grunt.

We're happy to announce the release of Assemble v0.13.0! If you're new to assemble, the About section and FAQ might be a good place to start.

Website is outdated and being refactored!

Assemble's website, assemble.io, only has information related to gulp-assemble. We're working hard to update the site with information about the latest release.

In the meantime, you might find the WIP docs useful. The unit tests are also great examples!

Get in touch!

Have questions? Suggestions? Want to discuss assemble? Join the conversation on gitter or give us a shout on twitter. The assemble team and community are always happy to help!

• About
• Install
• Getting started
  • Running tasks
  • API and CLI
• CLI
  • Tasks
  • Options
  • Object expansion
  • cwd
  • file
• API
• Templates API
• File System API
  • .src
  • .dest
  • .copy
  • .symlink
• Task API
  • .task
  • .build
  • .watch
• Release history
• Contributing
• FAQ
• Related projects
• Similar projects
• Authors
• License

(TOC generated by verb using markdown-toc)

What is Assemble?

Assemble makes it easy to create, customize, generate and maintain complete web projects. Here are some highlights:

• Expressive, imperative API that is powerful and easy to use.
• Facilitates the use of modular, encapsulated components in your markup, like pages, partials and layouts, resulting in consistent design across your projects.
• Extremely pluggable and easy to extend with helpers, plugins, routes, middleware or engines.
• Use any data source for rendering templates, making it easy to begin a project using mock data and switch "live" data source later on.
• First class collection support, with paging, pagination, lists (arrays), groups and sorting. Collections even support plugins and collection-specific routes.
• Use any template engine for rendering templates. You can even use multiple engines at once, Assemble will automatically detect the correct one to use on each template at render time.
• Transform content from markdown or any other plain text format to HTML using plugins, middleware helpers or engines.
• Full support for gulp plugins. Read our gulp FAQ for more info about gulp support.

Install with npm:

$ npm install assemble --save

If you plan on using assemble's CLI, you'll need to use an assemblefile.js. Otherwise, assemble can be used like any other node.js library.

Example

Render a template with with handlebars:

var assemble = require('assemble');
var app = assemble();
var locals = {title: 'Home!'};

// add a "page" 
app.page('home.hbs', {content: 'This is '});

// render it!
app.render('home.hbs', locals, function(err, view) {
  if (err) throw err;

  console.log(view.content);
  //=> 'This is Home!'
});

Create an assemblefile.js and add tasks to run:

var assemble = require('assemble');
var htmlmin = require('gulp-htmlmin');
var app = assemble();

app.page('a.hbs', {content: '...'});
app.page('b.hbs', {content: '...'});
app.page('c.hbs', {content: '...'});

app.task('default', function() {
   return app.toStream('pages')
    .pipe(app.renderFile())
    .pipe(htmlmin())
    .pipe(app.dest('site'));
});

// expose your instance of assemble
module.exports = app;

Use assemble via CLI or API

To run tasks, you can do one of the following:

• CLI: install Assemble globally then use the assemble command
• API: use the .build method

CLI: Install Assemble globally

Install assemble using npm with the following command:

$ npm i -g assemble

With assemble installed, you may now run assemble from any project that has an assemblefile.js in its root (the "root" of a project is wherever package.json is).

API: Use the .build method

(This can be in any file, not just an assemblefile.js)

app.build('default', function(err) {
  if (err) throw err;
  console.log('done!');
});

Learn more about tasks.

Run assemble from the command line.

$ assemble <tasks> [options]

Note that for most command line options, order or definition makes no difference, so tasks can be defined before or after options.

Optionally specify one or more tasks to run. Multiple tasks are separated by a space.

Example

To run tasks foo and bar, you would enter the following in the command line:

$ assemble foo bar

Non-task commands and options are prefixed with -- and are specified using any of the following formats:

• single value, like --foo, or
• key-value pair, like --foo=bar. Also, key-value pairs may be separated by either = or a single whitespace, so --foo=bar and --foo=bar should both work.

Additionally, as mentioned above, tasks may be defined before or after options, so both of the following are equivalent:

$ assemble --cwd foo bar
# or 
$ assemble foo bar --cwd

Example

To emit views as they're loaded and log them to stderr, run assemble with the following command:

$ assemble --emit view
# or
$ assemble --emit=view

Object-paths may be specified using dot-notation for either the key or value in a command line argument.

Additionally, assemble uses expand-object (and some custom parsing) to make it easier to pass non-trivial options and commands via command line. So all of the following formats are possible.

Examples

Boolean values:

$ assemble --foo 
# { foo: true }

Key-value pairs:

$ assemble --foo=bar
# { foo: 'bar' }

Nested booleans:

$ assemble --option=foo 
# {options: { foo: true }}

Nested key-value pairs:

$ assemble --option=foo:bar
# {options: { foo: 'bar' }}

Deeply nested key-value pairs:

$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}}

Or on the left-side of the =:

$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}}

Change the cwd for the assemblefile.js to run, optionally specifying any tasks to run:

$ assemble <tasks> --cwd [directory]

Example

To run the scaffolds example in the examples/ directory, you would enter:

$ assemble --cwd examples/scaffolds

If successful, in the command line, you should see something like this:

The name of which file to load when running, defaulting to assemblefile.js:

$ assemble --file assemblefile.dev.js

Create an assemble app. This is the main function exported by the assemble module.

Params

• options {Object}: Optionally pass default options to use.

Example

var assemble = require('assemble');
var app = assemble();

Assemble has an extensive API for working with templates and template collections. In fact, the entire API from the templates library is available on Assemble.

While we work on getting the assemble docs updated with these methods you can visit the templates library to learn more about the full range of features and options.

Assemble offers the following low-level methods for working with the file system:

• src
• symlink
• dest
• copy

Assemble has first-class support for vinyl-fs, so any gulp plugin can be used in your assemble pipeline.

Create a vinyl stream. Takes glob patterns or filepaths to the source files to read.

Params

• glob {String|Array}: Glob patterns or file paths to source files.
• options {Object}: Options or locals to merge into the context and/or pass to src plugins

Example

app.src('src/*.hbs');

// define `src` options
app.src('src/*.hbs', { layout: 'default' });

Specify a destination for processed files.

Params

• dest {String|Function}: File path or rename function.
• options {Object}: Options and locals to pass to dest plugins

Example

app.dest('dist/');

Copy files with the given glob patterns to the specified dest.

Params

• patterns {String|Array}: Glob patterns of files to copy.
• dest {String|Function}: Desination directory.
• returns {Stream}: Stream, to continue processing if necessary.

Example

app.task('assets', function() {
  // return, to let assemble know when the task has completed
  return app.copy('assets/**', 'dist/');
});

Same as .src but takes glob patterns or filepaths for the symlinks to read.

Params

• glob {String|Array}: Glob patterns or file paths

Example

app.symlink('src/*.hbs');

Assemble has the following methods for running tasks and controlling workflows:

• task
• build
• watch

Define a task to be run when the task is called.

Params

• name {String}: Task name
• fn {Function}: function that is called when the task is run.

Example

app.task('default', function() {
  app.src('templates/*.hbs')
    .pipe(app.dest('site/'));
});

Run one or more tasks.

Params

• tasks {Array|String}: Task name or array of task names.
• cb {Function}: callback function that exposes err

Example

app.build(['foo', 'bar'], function(err) {
  if (err) throw err;
  console.log('done!');
});

Watch files, run one or more tasks when a watched file changes.

Params

• glob {String|Array}: Filepaths or glob patterns.
• tasks {Array}: Task(s) to watch.

Example

app.task('watch', function() {
  app.watch('docs/*.md', ['docs']);
});

v0.13.0

• Bumps templates to v0.21.0. Support for the queue property was removed on collections. See templates for additional details.
• Fixes bug where glob parent was not being used for file.base, causing dest directory to be relative to cwd instead of glob parent in some cases.
• Some changes were made to context handling that effected one unit test out of ~1,000. although it's unlikely you'll be effected by the change, it warrants a minor bump
• Externalizes common templates tests to base-test-runner, so that assemble plugins and other base applications can use the tests
• Includes a fix from assemble-loader, where a bug caused renameKey to not always be used when defined on collection loader options.
• Includes fixes from templates for resolving layouts

v0.12.0

• Bumps assemble-core to v0.18.0, which includes a bump in templates. See the changelog on the templates library for more details.

v0.11.0

• debug methods and related code have been removed
• Bumps assemble-core to v0.17.0

v0.10.0

• Adds support for using es6 generators with tasks
• Bumps assemble-core to v0.15.0

v0.9.0

• Bumps several dependencies. No API changes, this is mostly an optimization release. Be sure to completely remove node_modules and reinstall all dependencies to avoid errors such as isRegistered is not a function

v0.8.0

• Updates composer to v0.11.0, which removes the .watch method in favor of using the base-watch plugin.
• Changes in templates. Please see v0.11.0 in templates history for more details.

v0.7.0

• Stability improvements and optimizations of the API introduced in v0.6.0.

v0.6.0

• Major refactor. Assemble was completely re-written from the ground-up as a standalone node.js library and is no longer a grunt plugin. Grunt plugin support has been moved to grunt-assemble. Please see that repo for additional details.

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

If Assemble doesn't do what you need, please let us know

Is the assemble website up-to-date?

No, it's completely out-of-date. If you're using grunt-assemble, some of the documentation at assemble.io might still be useful. If you're using assemble v0.6.0 and higher, the documentation is probably wrong in almost every way.

We're actively (daily) working on a refactor and it's a very high priority.

What's the difference between assemble-core and assemble?

Assemble adds a CLI, a few built-in view collections: pages, layouts, and partials, middleware for parsing front-matter, and a few other basic defaults that we've found many users expect. If you'd prefer different defaults, assemble-core is a great starting point.

If you want something that handles templates, rendering, engines, helpers, collections, etc. but you don't need to run tasks or work with the file system, then consider using templates instead of assemble-core.

I use gulp, why is it recommended to use assemble directly, instead of running assemble with gulp?

You can run gulp plugins with assemble, but it won't always work the other way around. This is because, as a build system, assemble does things that gulp doesn't do, like handle middleware.

For example, assemble's .src and .dest methods have built-in .onStream, .preWrite, and .postWrite middleware handlers. If you still wish to use gulp and your build cycle includes middleware that requires these handlers, you can use the assemble-handle plugin with gulp to ensure that the handlers are still called as needed.

This is a long way of saying, you can find ways to make gulp work, but you would just be adding an extra dependency to your project to do things that assemble already does.

What is the relationship between gulp and assemble?

Please read our gulp FAQ for more information.

You might also be interested in these projects from @doowb and @jonschlinkert:

• boilerplate: Tools and conventions for authoring and publishing boilerplates that can be generated by any build… more | homepage
• generate: Fast, composable, highly pluggable project generator with a user-friendly and expressive API. | homepage
• scaffold: Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… more | homepage
• update: Easily keep anything in your project up-to-date by installing the updaters you want to use… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

If assemble doesn't do what you need, there are some other great open source projects you might be interested in, created by our friends on GitHub (in alphabetical order):

Static site generators

• docpad
• metalsmith
• punch
• wintersmith

Blog frameworks

• hexojs
• ghost

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb, v0.9.0, on June 03, 2016.