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 docum
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 v0.7.0! Please see the release history to learn about new features, bug fixes and changes - breaking or otherwise.
What is Assemble?
Assemble makes it easy to create, customize, generate and maintain a complete static web project. Highlights:
(TOC generated by verb using markdown-toc)
Install with npm:
$ npm i 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
var assemble = require('assemble');
// create an instance of assemble
var app = assemble();
app.set('foo', 'bar');
console.log(app.get('foo'));
//=> 'bar'
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();
});
// expose your instance of assemble
module.exports = app;
Use assemble via CLI or API
To run tasks, you can do one of the following:
assemble command.build methodCLI: 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:
--foo, or--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:
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();
Load default plugins. Built-in plugins can be disabled on the assemble options.
Example
var app = assemble({
plugins: {
loader: false,
store: false
}
});
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:
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 pluginsExample
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 pluginsExample
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 pathsExample
app.symlink('src/*.hbs');
Assemble has the following methods for running tasks and controlling workflows:
Define a task to be run when the task is called.
Params
name {String}: Task namefn {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 errExample
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.7.0
v0.6.0
As of January 09, 2016:
Statements : 100% (38/38)
Branches : 100% (8/8)
Functions : 100% (10/10)
Lines : 100% (38/38)
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
Common questions we're asked about gulp and gulp plugins.
Does assemble wrap gulp?
No, but assemble does leverage some of the same libraries as gulp, including some libraries from the gulp team, such as vinyl, vinyl-fs (via the assemble-fs plugin), and bach (via composer).
Why does assemble use the same libraries?
Because they're great libraries, with great patterns, and they're well maintained.
More importantly, when we designed assemble's new API we felt strongly that it would be a disservice to the community to try to compete with a different plugin pattern than the one gulp has already established. We also tried very hard to ensure that gulp plugins could be used with assemble.
Why doesn't assemble use gulp?
We do use gulp quite extensively in many of our projects, in the way that gulp is used on most projects: with a gulpfile.js with plugins used for ensuring code quality, linting, unit tests, coverage, and sometimes more interesting and complex things that gulp is great at handling.
Beyond that, Assemble and gulp actually share very little in common in terms of high-level API and use cases. For example, the vast majority of assemble's methods are related to the following areas:
Here are the areas that assemble and gulp share in common (both bullets are introduced to assemble via plugins):
src, dest)task, watch)Gulp could probably handle all of the first items listed with a combination of plugins and (quite a bit of) custom code. But so could JavaScript.
What matters is that you choose the library that makes sense for what you need on a project-by-project basis. Don't try to fit a square peg in a round hole.
assemblefile.js doing things that could all easily be handled by gulp, then make your life easier and use a gulpfile with gulp instead.assemblefile.js and use assemble directly.However, despite all that has been mentioned, we initially wanted to use gulp as a library but decided to go a different direction and use composer for running tasks instead.
There were a few reasons for this:
.build method for running tasksIn the end it just made more sense to create our own library from the ground up, but composer still leverages bach for flow control.
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:
Static site generators
Blog frameworks
Jon Schlinkert
Brian Woodward
Copyright © 2016 Jon Schlinkert Released under the MIT license.
This file was generated by verb on January 09, 2016.
FAQs
Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit
The npm package assemble receives a total of 3,877 weekly downloads. As such, assemble popularity was classified as popular.
We found that assemble demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.