getting-started.md

title
Getting Started

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

Rendering templates

Render a template (the default engine is [handlebars][engine-handlebars], but you can use any engine you want):

var assemble = require('{%= name %}');
var app = assemble();

// add a "page"  nd render it!
app.page('home.hbs', {content: 'This is \{{title}}'})
  .render({title: 'Home!'}, 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;

Built-in Collections

Assemble has a few built-in collections, pages, partials and layouts.

Custom collections

Use the .create() method to create a custom template collection:

app.create('posts'[, options]);

When a new collection is created, the singular and plural forms of the collection name (in this example posts) are used to create methods for adding templates (and are automatically exposed on the assemble API).

Continuing with the posts collection example, the following methods would be added to assemble for adding templates to that collection:

• app.post()
• app.posts()

Collection types

There are three types of built-in collection "types" in assemble:

1. pages:
2. partials:
3. layouts:

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

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