assemble

assemble

Get the rocks out of your socks! Assemble makes you fast at web development! Used by thousands of projects for rapid prototyping, themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites/static site generator, an alternative to Jekyll for gh-pages and more! Gulp- and grunt-friendly.
Under MIT License
By assemble

javascript html nodejs static-site generator css gulp markdown pwa static-site-generator documentation scaffold templates build md docs blog-engine grunt assemble html-templates

assemble


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](#quickstart)
* [Installing assemble](#installing-assemble)
* [Installing assemble's CLI](#installing-assembles-cli)
* [assemblefile.js](#assemblefilejs)
- [CLI](#cli)
* [Running tasks](#running-tasks)
* [Specifying options](#specifying-options)
* [Object expansion](#object-expansion)
- [Command line options](#command-line-options)
* [cwd](#cwd)
* [file](#file)
- [API](#api)
* [Templates API](#templates-api)
+ [.create](#create)
+ [View types](#view-types)
+ [.engine](#engine)
+ [.render](#render)
* [File System API](#file-system-api)
+ [.src](#src)
+ [.dest](#dest)
+ [.copy](#copy)
+ [.renderFile](#renderfile)
* [Task API](#task-api)
+ [.task](#task)
+ [.build](#build)
+ [.watch](#watch)
- [Plugins](#plugins)
* [Discovering plugins](#discovering-plugins)
* [Authoring plugins](#authoring-plugins)
- [Learning](#learning)
* [Help](#help)
* [More information](#more-information)
* [FAQ](#faq)
- [About](#about)
* [Community](#community)
* [Related projects](#related-projects)
* [Similar projects](#similar-projects)
* [Release history](#release-history)
* [Contributing](#contributing)
* [Contributors](#contributors)
* [Authors](#authors)
* [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_

What is Assemble?

Assemble is a command line tool and developer framework for rapid prototyping, static site generation, and [much more](#what-can-i-do-with-assemble).

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](http://www.airbusgroup.com/int/en.html)
* [Diebold](http://www.diebold.com/)
* [Transformicons](http://www.transformicons.com/)
* [Barrel](https://www.barrelny.com/)
* [yesware](https://www.yesware.com/)
* [Amaze](https://www.amaze.com/)
* [sennheiser](http://sennheiser-d1.com/)
* [perf.rocks](http://perf.rocks/)
* [Milano JS](http://milanojs.com/)
* [AKQA](http://www.akqa.com/)
* [huxtaburger](http://www.huxtaburger.com.au/)
* [Typeplate](http://typeplate.com/)
* [Angular Basics](http://www.angularjsbook.com/)

Is your website, blog or project built with assemble? Please [let us know about it](../../issues/300)!

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](http://gulpjs.com) plugin
* [Powerful features](#features) for rapid web development, including a robust API for rendering templates with any node.js template engine.
* Assemble can use any [base](https://github.com/node-base/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](examples/blog)
* Styleguides
* Themes
* UI components
* [Project scaffolder](examples/generator) ([generate](https://github.com/generate/generate) is also built on assemble)
* [build tool](examples/build-tool)
* Documentation ([verb](https://github.com/verbose/verb) is built on assemble)
* Generate [boilerplates](examples/boilerplates), [scaffolds](examples/scaffold), and [targets](examples/targets)
* E-books ([Angular Basics](http://www.angularjsbook.com/) 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](https://github.com/generate/generate): scaffold out new projects from the command line
* [assemble](https://github.com/assemble/): <= you are here
* [verb](https://github.com/verbose/verb): generate documention for your projects
* [update](https://github.com/update/update): keep your projects up-to-date

Features

Here are just a few of the features assemble offers:

* Intuitive CLI
* Full support for [gulp](http://gulpjs.com) and [base](https://github.com/node-base/base) plugins
* Assemble templates are [vinyl](https://github.com/gulpjs/vinyl) files
* Render templates with any [template engine](#engine), including [nunjucks](https://github.com/assemble/assemble-nunjucks), [handlebars](https://github.com/jonschlinkert/engine-handlebars), [lodash](https://github.com/jonschlinkert/engine-lodash) and any consolidate engine!
* Use multiple engines, assemble can detect the one to use based on file extension
* [helpers](#helpers): support for sync and async
* [Templates collections](#collections)
* Pages
* Partials/includes
* [Layouts](https://github.com/doowb/layouts)
* Pagination
* [permalinks](https://github.com/assemble/assemble-permalinks)
* [middleware](#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:


sh
$ npm install -D assemble


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:


json
{
"scripts": {
"build": "assemble"
}
}


Then run


sh
$ npm run build


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.


sh
$ npm install --global assemble


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:


sh
$ assemble


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.


sh
$ assemble <tasks> [options]


Running tasks

Specify one or more space-separated tasks to run.


Examples


Run task foo


sh
$ assemble foo


Run tasks foo and bar


sh
$ assemble foo bar


Specifying options

Non-task options are prefixed with --.


Examples


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


sh
$ assemble --cwd=docs


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


sh
$ assemble --emit=view


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:


```sh
$ assemble --foo


{ foo: true }

```


Key-value pairs:


```sh
$ assemble --foo=bar


{ foo: 'bar' }

```


Nested booleans:


```sh
$ assemble --option=foo


{options: { foo: true }}

```


Nested key-value pairs:


```sh
$ assemble --option=foo:bar


{options: { foo: 'bar' }}

```


Deeply nested key-value pairs:


```sh
$ assemble --option=foo.bar.baz:qux


{options: foo: { bar: { baz: 'qux' }}}}

```


Or on the left-side of the =:


```sh
$ 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:


sh
$ assemble <tasks> --cwd [directory]


Example


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


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


sh
$ assemble --file assemblefile.dev.js


API
Assemble

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


Params



Example


js
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. 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:



.create

Create a template collection for caching views:


js
app.create('includes', {viewType: 'partial'});


Options



Add views


Add a view to the collection:


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


Add multiple views:


```js
app.includes({
path: 'foo.md', contents: new Buffer('this is contents'),
path: 'bar.md', contents: new Buffer('this is contents'),
path: 'baz.md', contents: new Buffer('this is contents')
});


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


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:



Defining view types


You can define view types when a collection is created:


js
app.create('snippet', {viewType: 'partial'});


Or directly on the collection options:


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


.engine

Register template engine for rendering views with the given ext:


js
app.engine(ext, fn);


Params



Example


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


// create a custom engine
app.engine('txt', function(str, locals, cb) {
// render str with locals
cb(null, str);
});
```


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


Example


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


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:


js
app.src('templates/*.*')
.pipe(app.renderFile('hbs'))


.render

Render a view with the given locals and callback.


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


Params


File System API

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



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



Example


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


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


.dest

Specify a destination for processed files.


Params



Example


js
app.dest('dist/');


.copy

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


Params



Example


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


.renderFile

Renders files as they are pushed through the stream.


js
app.src('*.hbs')
.pipe(app.renderfile())
.pipe(app.dest('foo'));


Force a specific engine to be used for rendering files:


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


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

Task API

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



.task

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


Params



Example


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


.build

Run one or more tasks.


Params



Example


js
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



Example


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



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

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.



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:



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



Blog frameworks



Release history

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



Custom labels used in this changelog:



0.24.0 - 2017-05-19

added



fixed



0.23.0 - 2017-02-11

dependencies



0.21.0 - 2017-02-03

dependencies



fixed



0.20.0 - 2017-02-02

dependencies



0.19.0 - 2017-02-01

dependencies



0.18.0

Dependencies



0.17.0

Dependencies



0.16.1

0.16.0

0.15.0

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.



0.13.0

0.12.0

0.11.0

0.10.0

0.9.0

0.8.0

0.7.0

[0.6.0]

(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 |
| 842 | doowb |
| 11 | AndersDJohnson |
| 7 | Arkkimaagi |
| 7 | stefanwalther |
| 4 | avr |
| 4 | bendrucker |
| 2 | thegreatsunra |
| 2 | rauberdaniel |
| 2 | onokumus |
| 2 | RobLoach |
| 2 | StevenBlack |
| 2 | xzyfer |
| 2 | ain |
| 1 | asans |
| 1 | bauerca |
| 1 | caseyg1204 |
| 1 | hyzhak |
| 1 | mootari |
| 1 | criticalmash |
| 1 | joonasy |
| 1 | jordanthomas |
| 1 | frayer |
| 1 | efender |
| 1 | pburtchaell |
| 1 | scmorrison |
| 1 | oncletom |
| 1 | tylerhowarth |
| 1 | klokie |


Authors

Jon Schlinkert



Brian Woodward



License

Copyright © 2017, Jon Schlinkert.
MIT

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