assemble

assemble

Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt, Less.js / lesscss.org, Topcoat, Web Experience Toolkit, and hundreds of other projects to build sites, themes, components, documentation, blogs and gh-pages.

Heads up!

Please visit the [grunt-assemble] repo if you use Assemble with Grunt. All development and related issues for Assemble's Grunt plugin will be conducted on that repostory.

Table of contents

• Install

  • Install CLI
  • Install locally

• Usage

  • Example: Templates
  • Example: Pre-process CSS

• Docs

  • Templates
    • .partial
    • .page
    • .layout
    • .engine
    • .helper

• Data

  • .data

• API

  • Run tests
  • Test coverage
  • Contributing
  • Authors
  • License

(Table of contents generated by verb)

Install

Install CLI

Install globally with npm

npm i -g assemble@beta

Install locally

Install locally with npm

npm i assemble@beta --save

Usage

Example assemblefile.js

var assemble = require('assemble');
var extname = require('gulp-extname');
var less = require('gulp-less');

assemble.task('html', function() {
  assemble.src('templates/*.hbs')
    .pipe(extname())
    .pipe(assemble.dest('dist/'));
});

assemble.task('css', function () {
  assemble.src('styles/*.less')
    .pipe(less())
    .pipe(assemble.dest('dist/assets/css'));
});

assemble.task('default', ['html', 'css']);

Example: Templates

Generate HTML from templates. (Assemble automatically renders handlebars templates, but custom engines and plugins may also be used.)

var assemble = require('assemble');
var extname = require('gulp-extname');

assemble.task('default', function () {
  assemble.src('templates/*.hbs')
    .pipe(extname())
    .pipe(assemble.dest('dist'));
});

Run assemble from the command line to run the default task in your assemblefile.js.

Example: Pre-process CSS

Using a plugin

Use plugins to pre-process CSS (Assemble can run any gulp plugin):

var assemble = require('assemble');
var less = require('gulp-less');

assemble.task('css', function () {
  assemble.src('styles/*.less')
    .pipe(less())
    .pipe(assemble.dest('dist/assets/css'));
});

assemble.task('default', ['css']);

Or, using an engine

Instead of a plugin you can register an engine, such as engine-less.

(Engines are run automatically on any files that have a file extension matching the name that you used when registering the engine.)

var assemble = require('assemble');
assemble.engine('less', require('engine-less'));

assemble.task('css', function () {
  assemble.src('styles/*.less')
    .pipe(assemble.dest('dist/assets/css'));
});

assemble.task('default', ['css']);

---

Docs

Templates

.partial

Add partials to be used in other templates.

assemble.partial('notice', { content: '<strong>...</strong>' });
assemble.partial('banner', { content: '/*! Copyright (c) 2014 Jon Schlinkert, Brian Woodward... */' });
// or load a glob of partials
assemble.partials('partials/*.hbs');

// optionally pass locals, all template types support this
assemble.partials('partials/*.hbs', {site: {title: 'Code Project'}});

Usage

Use the partial helper to inject into other templates:

{{partial "banner"}}

Get a cached partial:

var banner = assemble.views.partials['banner'];

.page

Add pages that might be rendered (really, any template is renderable, pages fit the part though)

assemble.page('toc.hbs', { content: 'Table of Contents...'});
// or load a glob of pages
assemble.pages('pages/*.hbs', {site: {title: 'Code Project'}});

Use the page helper to inject pages into other templates:

{{page "toc"}}

Get a cached page:

var toc = assemble.views.pages['toc'];

Pages are renderable templates, so they also have a .render() method:

var toc = assemble.views.pages['toc'];
// async
toc.render({}, function(err, content) {
  console.log(content);
});

// or sync
var res = toc.render();

Params

• locals {Object}: Optionally pass locals as the first arg
• callback {Function}: If a callback is passed, the template will be rendered async, otherwise sync.

.layout

Add layouts, which are used to "wrap" other templates:

assemble.layout('default', {content: [
  '<!DOCTYPE html>',
  '  <html lang="en">',
  '  <head>',
  '    <meta charset="UTF-8">',
  '    <title>{%= title %}</title>',
  '  </head>',
  '  <body>',
  '    {% body %}', // `body` is the insertion point for another template
  '  </body>',
  '</html>'
].join('\n')});

// or load a glob of layouts
assemble.layouts('layouts/*.hbs', {site: {title: 'Code Project'}});

Layouts may be use with any other template, including other layouts. Any level of nesting is also possible.

Body tags

Layouts use a body as the insertion point for other templates. The syntax assemble uses for the body tag is:

{% body %}

Admittedly, it's a strange syntax, but that's why we're using it. assemble shouldn't collide with templates that you might be using in your documentation.

Usage

Layouts can be defined in template locals:

// either of these work (one object or two)
assemble.page('toc.hbs', { content: 'Table of Contents...'}, { layout: 'default' });
assemble.partial('foo.hbs', { content: 'partial stuff', layout: 'block' });

Or in the front matter of a template. For example, here is how another layout would use our layout example from earlier:

// using this 'inline' template format to make it easy to see what's happening
// this could be loaded from a file too
assemble.layout('sidebar', {content: [
  '---',
  'layout: default',
  '---',
  '<div>',
  ' {% body %}',
  '</div>'
].join('\n')});

.engine

Add engines for rendering templates.

// render any files with a `.tmpl` extension using engine-lodash
assemble.engine('tmpl', require('engine-lodash'));

// render any files with a `.less` extension using engine-less
assemble.engine('less', require('engine-less'));

.helper

Add helpers to be used in templates.

Helpers are passed to the template engine being used at render time.

Custom helper

assemble.helper('read', function(filepath) {
  return fs.readFileSync(filepath, 'utf8');
});
//=> {{read "foo.txt"}}

Register a glob of helpers

assemble.helpers('helpers/*.js');

Pro tip

If you want to publish your helpers and share them with the community, make them as generic as possible so they work with any template engine.

Data

.data

Load data to pass to templates.

Any of these work:

assemble.data({foo: 'bar'});
assemble.data('package.json');
assemble.data(['foo/*.{json,yml}']);

API

.src

Specify source files using glob patterns or filepaths. Options may be passed as a second argument.

Params

• patterns {String|Array|Function}: Glob patterns, file paths, or renaming function.
• options {Object}: Options to pass to source plugins.

Example

assemble.src('src/*.hbs', {layout: 'default'});

// usage in a task
assemble.task('site', function() {
  assemble.src('src/*.hbs', {layout: 'default'})
    .pipe(assemble.dest('dist'));
});

.dest

Specify the destination for processed files. Options may be passed as a second argument.

Params

• dest {String}: Destination directory
• options {Object}: Options to be passed to dest plugins.

Example

assemble.dest('_gh_pages/', {ext: '.html'});

.copy

Copy a glob of files to the specified dest.

Params

• filepath {String|Array}: Source file path and/or glob patterns.
• dest {String|Function}: Destination folder or function for renaming.
• options {Object}: Additional options
• returns {Stream}: Stream to allow doing additional work.

Example

assemble.copy('assets/**', 'dist/');

// usage in a task
assemble.task('copy-assets', function() {
  return assemble.copy('assets/**', 'dist/');
});

.task

Define an assemble task. (read more about tasks)

Params

• name {String}: Task name
• fn {Function}

Example

assemble.task('default', function() {
  assemble.src('templates/*.hbs')
    .pipe(assemble.dest('dist/'));
});

.files

files is a session-context-specific getter that returns the collection of files from the current task.

• returns {Object}: Get the files from the current task.

Example

var files = assemble.files;

.watch

Rerun the specified task when a file changes.

Params

• glob {String|Array}: Filepaths or glob patterns.
• options {String}
• fn {Function}: Task(s) to watch.
• returns {String}

Example

assemble.watch('docs/*.md', ['docs']);

// usage in a task
assemble.task('watch', function() {
  assemble.watch('docs/*.md', ['docs']);
});

.init

Create a new instance of Assemble.

Example

assemble.init();

Run tests

Install dev dependencies:

npm i -d && npm test

Test coverage

Statements   : 79.47% ( 209/263 )
Branches     : 52.44% ( 43/82 )
Functions    : 82.93% ( 34/41 )
Lines        : 80% ( 208/260 )

Contributing

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

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright (c) 2014-2015 Assemble Copyright (c) 2014 Fractal [e-mail] (for completions and CLI) Released under the MIT license.

---

This file was generated by verb-cli on April 29, 2015.