assemble

assemble

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! Plugins for gulp and grunt are also supported.

We're happy to announce the release of Assemble v<%= version %>! Please see the release history to learn about new features, bug fixes and changes - breaking or otherwise.

About

What is Assemble?

Assemble makes it easy to create, customize, generate and maintain a complete static web project. Highlights:

• Facilitates the use of modular, encapsulated components, like pages, partials and layouts, resulting in consistent design across your project
• Assemble is extremely pluggable and easy to extend with helpers, plugins, middleware or engines.
• Ability to use any data source for rendering templates, which makes it easy to begin a project using mock data and switch to a "live" data source later on.
• 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.
• Makes it easy to transform content from markdown or any other plain text format to HTML using plugins, middleware helpers or engines.
• Assemble has full support for gulp plugins

• Install
• Getting started
  • Running tasks
• CLI
  • Tasks
  • Options
  • Object expansion
• API
• Templates API
• File System API
  • .src
  • .dest
  • .copy
  • .symlink
• Task API
  • .task
  • .build
  • .watch
• Release history
• Test coverage
• Contributing
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm i assemble --save

Getting started

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

Running tasks

Create an assemblefile.js with the following task:

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

app.task('default', function(cb) {
  console.log('it worked!');
  cb();
});

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.

CLI

Run assemble from the command line.

$ assemble <tasks> [options]

Tasks

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

Options

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.

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 expansion

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' }}}}

API

Assemble

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();

Templates API

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][templates] to learn more about the full range of features and options.

---

File System API

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.

.src

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' });

.dest

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

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/');
});

.symlink

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');

---

Task API

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

• task
• build
• watch

.task

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/'));
});

.build

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

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']);
});

Release history

v0.7.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.

Test coverage

As of January 05, 2016:

Statements : 100% (38/38)
Branches   : 100% (8/8)
Functions  : 100% (10/10)
Lines      : 100% (38/38)

Contributing

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

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb on January 05, 2016.

Changelog

[0.7.0]

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