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)

Quickstart

Installing assemble

Add assemble your project's

devDependencies

$ npm install -D assemble

You should now be able to run assemble directly (using

node assemblefile.js

npm

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

Then run

$ npm run build

Installing assemble's CLI

You can also assemble's CLI globally, which adds the

assemble

$ 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

$ assemble

If no

assemblefile.js

assembfile.js

CLI

Run assemble from the command line.

$ assemble  [options]

Running tasks

Specify one or more space-separated tasks to run.

Examples

Run task

foo

$ assemble foo

Run tasks

foo

bar

$ assemble foo bar

Specifying options

Non-task options are prefixed with

--

Examples

Set the

--cwd

$ 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

assemblefile.js

$ assemble  --cwd [directory]

Example

To run the

scaffolds

examples/

$ 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

API

Assemble

Create an

assemble

Params

• options

  {Object}: Optionally pass default options to use.

Example

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:

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

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

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:

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

Add multiple views:

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:

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

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

Or directly on the collection options:

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

.engine

Register template engine for rendering views with the given

ext

app.engine(ext, fn);

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

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

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

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

.render

Render a view with the given

locals

callback

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

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

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

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

.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

app.dest('dist/');

.copy

Copy files with the given glob

patterns

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/');
});

.renderFile

Renders files as they are pushed through the stream.

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

Force a specific engine to be used for rendering files:

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

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

.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

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

• glob

  {String|Array}: Filepaths or glob patterns.

• tasks

  {Array}: Task(s) to watch.

Example

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

• base: find base plugins on npm using the

  baseplugin

  keyword
• assemble: find assemble plugins on npm using the

  assembleplugin

  keyword
• generate: find generate plugins on npm using the

  generateplugin

  keyword
• templates: find templates plugins on npm using the

  templatesplugin

  keyword
• update: find update plugins on npm using the

  updateplugin

  keyword
• verb: find verb plugins on npm using the

  verbplugin

  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

partials

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

.dest

.onStream

.preWrite

.postWrite

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 assemble

  assemble

  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 where

  isbinaryfile

  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 that

  view

  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 to

  dest

  handling

0.19.0 - 2017-02-01

dependencies

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

  list

  s

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 the

  renameKey

  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

getView

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

  queue

  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 caused

  renameKey

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

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