Assemble

Get the rocks out of your socks! Assemble makes you fast at web development...

Static site generator
assemble/assembleassemble.io/assemble

README


assemble

NPM version NPM monthly downloads Build Status Gitter

Looking for the grunt plugin? Please visit grunt-assemble.

_(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)_.

Overview


_(Click the following sections to expand them)_

Table of contents

- Quickstart
  Installing assemble
  Installing assemble's CLI
  assemblefile.js
- CLI
  Running tasks
  Specifying options
  Object expansion
- Command line options
  cwd
  file
- API
  Templates API
    + .create
    + View types
    + .engine
    + .render
  File System API
    + .src
    + .dest
    + .copy
    + .renderFile
  Task API
    + .task
    + .build
    + .watch
- Plugins
  Discovering plugins
  Authoring plugins
- Learning
  Help
  More information
  FAQ
- About
  Community
  Related projects
  Similar projects
  Release history
  Contributing
  Contributors
  Authors
  License

_(TOC generated by verb using markdown-toc)_
What is Assemble?

Assemble is a command line tool and developer framework for rapid prototyping, static site generation, and much more.
Who uses assemble?

Assemble is used by thousands of developers and teams in more than 170 countries! Here are a few examples of sites built with assemble:

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

Is your website, blog or project built with assemble? Please let us know about it!
Why should I use assemble?

Expressive, functional API (the API is also stable)
You can use assemble with any web framework or CSS/HTML toolkit
Assemble can build static sites or hybrid static/dynamic sites
Streams support, you can run any gulp plugin
Powerful features for rapid web development, including a robust API for rendering templates with any node.js template engine.
Assemble can use any base plugin
Assemble can do anything Jekyll does, but with more flexibility and control
Like gulp, assemble can also run any other static site generator as a plugin, which means you can do anything and everything all other node.js static site generators can do, and much more.
What can I do with Assemble?

Rapid prototyping
Static site generation (more powerful alternative to jekyll)
Landing pages
A/B testing
blogs
Styleguides
Themes
UI components
Project scaffolder (generate is also built on assemble)
build tool
Documentation (verb is built on assemble)
Generate boilerplates, scaffolds, and targets
E-books (Angular Basics was built with assemble)
Much more!

Rapid development toolkit

Assemble can be used standalone, but it's even more powerful when used alongside the following libraries:

generate: scaffold out new projects from the command line
assemble: <= you are here
verb: generate documention for your projects
update: keep your projects up-to-date

Features

Here are just a few of the features assemble offers:

Intuitive CLI
Full support for gulp and base plugins
Assemble templates are vinyl files
Render templates with any template engine, including nunjucks, handlebars, lodash and any consolidate engine!
Use multiple engines, assemble can detect the one to use based on file extension
helpers: support for sync and async
Templates collections
Pages
Partials/includes
Layouts
Pagination
permalinks
middleware can be used to tranform files at any stage in the render cycle
Generate pages from JSON
Much more!


Quickstart


Installing assemble


Add assemble your project's devDependencies using npm:

  1. ```sh
  2. $ npm install -D assemble
  3. ```

You should now be able to run assemble directly (using node assemblefile.js etc) or using npm scripts. For example, add the following to package.json:

  1. ``` json
  2. {
  3.   "scripts": {
  4.     "build": "assemble"
  5.   }
  6. }
  7. ```

Then run

  1. ```sh
  2. $ npm run build
  3. ```

Installing assemble's CLI


You can also assemble's CLI globally, which adds the assemble command to your system path, allowing it to be run from any directory.

  1. ```sh
  2. $ npm install --global assemble
  3. ```

_Note that even if assemble is installed globally, it's good practice to install it locally in every project to ensure that your projects are protected against any potentially breaking changes that might occur in assemble between development cycles._

assemblefile.js


To use assemble's CLI, you'll need to add an assemblefile.js to your project. The fastest way to do this is to run the following command:

  1. ```sh
  2. $ assemble
  3. ```

If no assemblefile.js exists in the current project, assemble will ask if you want to add one. If you answer yes, assemble will then generate a basic assembfile.js for you.

CLI


Run assemble from the command line.

  1. ```sh
  2. $ assemble <tasks> [options]
  3. ```

Running tasks


Specify one or more space-separated tasks to run.

Examples

Run task foo

  1. ```sh
  2. $ assemble foo
  3. ```

Run tasks foo and bar

  1. ```sh
  2. $ assemble foo bar
  3. ```

Specifying options


Non-task options are prefixed with --.

Examples

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

  1. ```sh
  2. $ assemble --cwd=docs
  3. ```

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

  1. ```sh
  2. $ assemble --emit=view
  3. ```

See more 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:

  1. ```sh
  2. $ assemble --foo
  3. # { foo: true }
  4. ```

Key-value pairs:

  1. ```sh
  2. $ assemble --foo=bar
  3. # { foo: 'bar' }
  4. ```

Nested booleans:

  1. ```sh
  2. $ assemble --option=foo
  3. # {options: { foo: true }}
  4. ```

Nested key-value pairs:

  1. ```sh
  2. $ assemble --option=foo:bar
  3. # {options: { foo: 'bar' }}
  4. ```

Deeply nested key-value pairs:

  1. ```sh
  2. $ assemble --option=foo.bar.baz:qux
  3. # {options: foo: { bar: { baz: 'qux' }}}}
  4. ```

Or on the left-side of the =:

  1. ```sh
  2. $ assemble --option.foo.bar.baz=qux
  3. # {options: foo: { bar: { baz: 'qux' }}}}
  4. ```

Command line options


cwd


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

  1. ```sh
  2. $ assemble <tasks> --cwd [directory]
  3. ```

Example

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

  1. ```sh
  2. $ assemble --cwd examples/scaffolds
  3. ```

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

screen shot 2016-01-09 at 1 35 52 pm

file


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

Example

  1. ```sh
  2. $ assemble --file assemblefile.dev.js
  3. ```

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

  1. ``` js
  2. var assemble = require('assemble');
  3. var app = assemble();
  4. ```

Templates API


Assemble exposes the entire API from the templates library for working with templates and template collections. The API is much more extensive than what is documented here, see templates for more documentation.

Templates and Views

In the following documentation, the terms "template" and "view" both refer to _aspects_ of the same thing. Here's what they mean:

template: an actual template string
view: a object with a content property that contains the template string. Since views are instances of vinyl, you can think of a view as a "vinyl file for templates".

.create


Create a template collection for caching views:

  1. ``` js
  2. app.create('includes', {viewType: 'partial'});
  3. ```

Options

cwd {String}: the base directory to use when loading templates onto the collection from a glob

viewType: {String|Array}: One or more view types to associate with the collection

Add views

Add a view to the collection:

  1. ``` js
  2. app.include('foo.md', {contents: new Buffer('this is contents')});
  3. ```

Add multiple views:

  1. ``` js
  2. app.includes({
  3.   path: 'foo.md', contents: new Buffer('this is contents'),
  4.   path: 'bar.md', contents: new Buffer('this is contents'),
  5.   path: 'baz.md', contents: new Buffer('this is contents')
  6. });

  8. // or pass a glob (optionally override `cwd` defined on `.create`)
  9. app.includes('*.{md,hbs}', {cwd: 'templates/includes'});
  10. ```

View types


View types are defined on a collection to determine how a templates in the collection will be handled throughout the [render cycle][].

Available types

Assemble supports three view types:

partial: Views with this type are can be used as "partials" (or "partial views"), which can be injected into other views. Useful for components, document fragments, or other snippets of reusable code or content. These views are passed to rendering engines to be used as partials, or variables on the context if partials are not directly supported.
layout: allows views to "wrap" other views (of any type, including other layouts or partials) with common code or content.
renderable: Views that have a one-to-one relationship with rendered files that will eventually be visible to a user or visitor to a website. For example: pages or blog posts. The renderable view type is automatically set if no other view types are set.

Defining view types

You can define view types when a collection is created:

  1. ``` js
  2. app.create('snippet', {viewType: 'partial'});
  3. ```

Or directly on the collection options:

  1. ``` js
  2. app.create('snippet');
  3. app.snippets.option('viewType', ['partial']); // string or array
  4. ```

.engine


Register template engine for rendering views with the given ext:

  1. ``` js
  2. app.engine(ext, fn);
  3. ```

Params

ext {String}: The file extension of files to render with the engine
fn {Function}: Async function that follows consolidate engine conventions, and takes three arguments:str, locals and callback.

Example

  1. ``` js
  2. // this engine is already registered in assemble
  3. app.engine('hbs', require('engine-handlebars'));

  5. // create a custom engine
  6. app.engine('txt', function(str, locals, cb) {
  7.   // render `str` with `locals`
  8.   cb(null, str);
  9. });
  10. ```

You can tell assemble to use the same engine for all file extensions by setting a value on options.engine.

Example

  1. ``` js
  2. // use engine `hbs` for rendering all files
  3. app.option('engine', 'hbs');
  4. ```

Or, if you're using .renderFile, you can force a specific engine to be used by passing the engine name.

Example

Use the hbs engine to render all templates:

  1. ``` js
  2. app.src('templates/*.*')
  3.   .pipe(app.renderFile('hbs'))
  4. ```

.render


Render a view with the given locals and callback.

  1. ``` js
  2. app.render(view, {title: 'Foo'}, function(err, view) {
  3.   // `view` is an object with a rendered `content` property
  4. });
  5. ```

Params

view {Object|String}: The view to render
locals {Object}: Locals to pass to template engine for rendering templates in view
callback {Function}


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

  1. ``` js
  2. app.src('src/*.hbs');

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

.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

  1. ``` js
  2. app.dest('dist/');
  3. ```

.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

  1. ``` js
  2. app.task('assets', function() {
  3.   // return, to let assemble know when the task has completed
  4.   return app.copy('assets/**', 'dist/');
  5. });
  6. ```

.renderFile


Renders files as they are pushed through the stream.

  1. ``` js
  2. app.src('*.hbs')
  3.   .pipe(app.renderfile())
  4.   .pipe(app.dest('foo'));
  5. ```

Force a specific engine to be used for rendering files:

  1. ``` js
  2. app.engine('txt', function(str, locals, cb) {
  3.   cb(null, str);
  4. });

  6. app.src('*.hbs')
  7.   .pipe(app.renderfile('txt')) //<= use engine `txt`
  8.   .pipe(app.dest('foo'));
  9. ```


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

  1. ``` js
  2. app.task('default', function() {
  3.   app.src('templates/*.hbs')
  4.     .pipe(app.dest('site/'));
  5. });
  6. ```

.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

  1. ``` js
  2. app.build(['foo', 'bar'], function(err) {
  3.   if (err) throw err;
  4.   console.log('done!');
  5. });
  6. ```

.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

  1. ``` js
  2. app.task('watch', function() {
  3.   app.watch('docs/*.md', ['docs']);
  4. });
  5. ```

Plugins


Discovering plugins


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

base: find base plugins on npm using thebaseplugin keyword
assemble: find assemble plugins on npm using theassembleplugin keyword
generate: find generate plugins on npm using thegenerateplugin keyword
templates: find templates plugins on npm using thetemplatesplugin keyword
update: find update plugins on npm using theupdateplugin keyword
verb: find verb plugins on npm using theverbplugin 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 (Temporarily, while we work on the new website, docs can be found in support/docs/src)
API documentation
Generators 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


Get updates on Assemble's development and chat with the project maintainers and community members.

Follow @assemblejs on Twitter.

If you like Assemble and want to tweet about it, please feel free to mention @assemblejs or use the #assemble hashtag

Read and subscribe to The Official Assemble Blog.
Join the official Slack room.
Join the conversation on Gitter

Tell us about your assemble project
Show your love by starring Assemble!
Get implementation help on StackOverflow (please use the assembleassemble tag in questions)
Gitter Discuss Assemble with us on Gitter

For maximum discoverability, plugin developers should use the keyword assembleplugin on packages which modify or add to the functionality of Assemble when distributing through npm or similar delivery mechanisms.

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


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.

0.24.0 - 2017-05-19


added

By popular request, assemble now automatically expands config templates in yaml front-matter, via expand-front-matter! This is a feature that we had in grunt-assemble, and users let us know that they wanted it back.

fixed

Updated dependencies to use is-binary-buffer, which fixes a bug whereisbinaryfile was trying to read from a file that didn't exist.

0.23.0 - 2017-02-11


dependencies

Bumps assemble-core to get an update to assemble-streams that ensures thatview is decorated with .toStream() when created by app (versus a collection).

0.21.0 - 2017-02-03


dependencies

Bumps assemble-loader to v1.0.0 to take advantage of optimizations, improvements and bug fixes related to loading views

fixed

Regression in 0.20.0 that was causing view.stat to be null in some cases after view.path changed
view.base was not always correct on views that were not created from the file system

0.20.0 - 2017-02-02


dependencies

Bumps assemble-core to v0.29.0 to take advantage of improvements todest handling

0.19.0 - 2017-02-01


dependencies

Bumps assemble-core to v0.28.0 to take advantage of new methods available onlists

0.18.0

Dependencies

bumps assemble-core to 0.27.0

0.17.0

Dependencies

bumps assemble-core to 0.26.0

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

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

0.15.0

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

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

0.13.0

Bumps assemble-core to v0.21.0. Support for thequeue 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 causedrenameKey to not always be used when defined on collection loader options.
Includes fixes from templates for resolving layouts

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

0.11.0

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

0.10.0

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

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

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

0.7.0

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

[0.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.

_(Changelog generated by helper-changelog)_

Contributing


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

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

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

Contributors


**Commits****Contributor**
------
1497[jonschlinkert](https://github.com/jonschlinkert)
842[doowb](https://github.com/doowb)
11[AndersDJohnson](https://github.com/AndersDJohnson)
7[Arkkimaagi](https://github.com/Arkkimaagi)
7[stefanwalther](https://github.com/stefanwalther)
4[avr](https://github.com/avr)
4[bendrucker](https://github.com/bendrucker)
2[thegreatsunra](https://github.com/thegreatsunra)
2[rauberdaniel](https://github.com/rauberdaniel)
2[onokumus](https://github.com/onokumus)
2[RobLoach](https://github.com/RobLoach)
2[StevenBlack](https://github.com/StevenBlack)
2[xzyfer](https://github.com/xzyfer)
2[ain](https://github.com/ain)
1[asans](https://github.com/asans)
1[bauerca](https://github.com/bauerca)
1[caseyg1204](https://github.com/caseyg1204)
1[hyzhak](https://github.com/hyzhak)
1[mootari](https://github.com/mootari)
1[criticalmash](https://github.com/criticalmash)
1[joonasy](https://github.com/joonasy)
1[jordanthomas](https://github.com/jordanthomas)
1[frayer](https://github.com/frayer)
1[efender](https://github.com/efender)
1[pburtchaell](https://github.com/pburtchaell)
1[scmorrison](https://github.com/scmorrison)
1[oncletom](https://github.com/oncletom)
1[tylerhowarth](https://github.com/tylerhowarth)
1[klokie](https://github.com/klokie)

Authors


Jon Schlinkert

github/jonschlinkert
twitter/jonschlinkert

Brian Woodward

github/doowb
twitter/doowb

License


Copyright © 2017, Jon Schlinkert.
MIT


_This file was generated by verb-generate-readme, v0.6.0, on December 27, 2017._