assemble

Welcome to Assemble v0.16.2!

Assemble is a command line tool and developer framework for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites / static site generator, alternative to jekyll for gh-pages and more!

(Note that the current website, assemble.io, is for grunt-assemble. Thanks for your patience while we work on updating the site with documentation for the latest assemble).

Who uses assemble?

Assemble is used by thousands of projects, including:

• Airbus Group
• hillaryclinton.com
• Diebold
• Transformicons
• Barrel
• yesware
• Amaze
• sennheiser
• perf.rocks
• Milano JS
• AKQA
• huxtaburger
• Typeplate
• Angular Basics

Features

Assemble can be used to create:

• blogs
• build system
• documentation
• e-books
• front-end UI
• generate boilerplates
• generate targets
• landing pages
• project generator
• project scaffolds
• rapid prototyping
• static site generator
• styleguides
• themes

Project lifecycle

As a standalone library, assemble can be used for creating, building and maintaining entire web projects. But it's even more powerful when used longside the following libraries:

• generate: scaffold out new projects
• assemble: build web projects (<= you are here)
• verb: create project documention
• update: maintain projects

Assemble also has a grunt plugin and can be used alongside gulp.

Features

• Full support for gulp plugins
• Support for base plugins
• Assemble templates are vinyl files
• render templates with any template engine, including nunjucks, handlebars, lodash and any consolidate engine!
• helpers: support for sync and async
• templates collections support
• partials and includes
• layouts
• pages
• custom template "types"
• pagination
• [permalinks][assemble-permalinks]
• middleware can be used to tranform files at any stage in the render cycle
• pagination
• Much more!

Table of contents

• Getting started
  • Install assemble
  • Example usage
    • Rendering templates
    • Running tasks
• CLI
  • Running tasks
  • Specifying options
  • Object expansion
• Command line options
  • cwd
  • file
• API
  • Templates API
    • .create
  • File System API
    • .src
    • .dest
    • .copy
    • .symlink
  • Task API
    • .task
    • .build
    • .watch
• Plugins
  • Discovering plugins
  • Authoring plugins
• Learning
  • Help
  • More information
  • FAQ
• About
  • Community
  • Related projects
  • Similar projects
  • Release history
  • Contributing
  • Authors
  • License

(TOC generated by verb using markdown-toc)

Getting started

Install assemble

To use assemble's CLI, you will first need to install it globally using npm:

$ npm --global install assemble

This adds the assemble command to your system path, allowing it to be run from any directory.

Example usage

Rendering templates

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

Running tasks

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') //<= push "pages" collection into stream
    .pipe(app.renderFile()) //<= render pages with default engine (hbs)
    .pipe(htmlmin()) //<= gulp plugin for minifying html
    .pipe(app.dest('site')); //<= write files to the "./site" directory
});

// expose your instance of assemble to assemble's CLI
module.exports = app;

CLI

Run assemble from the command line.

$ assemble <tasks> [options]

Running tasks

Specify one or more space-separated tasks to run.

Examples

Run task foo

$ assemble foo

Run tasks foo and bar

$ assemble foo bar

Specifying options

Non-task options are prefixed with --.

Examples

Set the --cwd to run an assemblefile.js in a different directory:

$ assemble --cwd=docs

Emit views as they're loaded and log them to stderr:

$ assemble --emit=view

See more [command line options](#command line options)

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

Command line options

cwd

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:

file

Specify the name of the config file for assemble's CLI to run, the default is assemblefile.js.

Example

$ assemble --file assemblefile.dev.js

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 exposes the entire API from the templates library for working with templates and template collections.

.create

Create a template collection.

app.create('includes');

Add views to the collection.

---

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

Plugins

Discovering plugins

Plugins from any applications built on base should work with Assemble and can be used in your assemblefile.js:

• [base][base-plugin]: find base plugins on npm using the baseplugin keyword
• [assemble][assemble-plugin]: find assemble plugins on npm using the assembleplugin keyword
• [generate][generate-plugin]: find generate plugins on npm using the generateplugin keyword
• [templates][templates-plugin]: find templates plugins on npm using the templatesplugin keyword
• [update][update-plugin]: find update plugins on npm using the updateplugin keyword
• [verb][verb-plugin]: find verb plugins on npm using the verbplugin keyword

Authoring plugins

Visit the plugin documentation guide to learn how to use, author and publish plugins.

Learning

Help

Get in touch!

Have questions, suggestions, or 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!

More information

• Documentation
• API documentation
• Generaters maintained by the core team

FAQ

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!

Is the assemble website up-to-date?

No, as mentioned above, 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.

About

Community

Are you using assemble in your project? Have you published an assemble project and want to share your project with the world?

Here are some suggestions!

• If you get like Assemble and want to tweet about it, please feel free to mention @assemble or use the #assemble hashtag
• Tell us about your assemble project
• Show your love by starring Assemble and assemble
• Get implementation help on StackOverflow (please use the assemble tag in questions)
• Gitter Discuss Assemble with us on Gitter
• If you publish an assemble plugin, thank you! To make your project as discoverable as possible, please add the keyword assembleplugin to package.json.

Contributing

Please read our contributing guide if you'd like to learn more about contributing to this project.

Related projects

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

• boilerplate: Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be… more | [homepage](https://github.com/jonschlinkert/boilerplate "Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be consumed by any build system or project scaffolding tool.")
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• scaffold: Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… more | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Similar projects

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

Release history

key

Changelog entries are classified using the following labels (from keep-a-changelog):

• added: for new features
• changed: for changes in existing functionality
• deprecated: for once-stable features removed in upcoming releases
• removed: for deprecated features removed in this release
• fixed: for any bug fixes

Custom labels used in this changelog:

• dependencies: bumps dependencies
• housekeeping: code re-organization, minor edits, or other changes that don't fit in one of the other categories.

v0.17.0

Dependencies

• bumps assemble-core to 0.26.0

v0.16.1

• bump dependencies. In particular, there was a bug in parser-front-matter where leading whitespace was removed after extracting front-matter, which caused the first line of indentation to be removed. This has been fixed.

v0.16.0

• Added: .log() method, which also exposes additional methods, like .log.info(), .log.success(), etc.
• docs were moved to support/docs, so that markdown docs can be built to the docs directory
• docs were updated, new docs added
• Moves some private prototype methods to static methods, to allow them to be used without creating an instance
• Bumps assemble-core to v0.25.0

v0.15.0

• Bumps assemble-core to v0.24.0 to get the latest versions of templates and base-data which removes the renameKey option from the .data method. Use the namespace option instead.

v0.14.0

Bumps assemble-core to v0.22.0 to take advantage of fixes and improvements to lookup methods: .find and getView. No API changes were made. Please let us know if regressions occur.

• fixes List bug that was caused collection helpers to explode
• Improvements to lookup functions: app.getView() and app.find()
• Bumps base to take advantages of code optimizations.

v0.13.0

• Bumps assemble-core to v0.21.0. Support for the queue property was removed on collections. See assemble-core 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.

Contributing

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

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

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

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

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

---

This file was generated by verb-generate-readme, v0.1.28, on August 06, 2016.