<p align="center"> <a href="https://github.com/assemble/assemble"> <img height="250" width="250" src="https://raw.githubusercontent.com/assemble/assemble/master/docs/logo.png"> </a> </p>

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)

<details> <summary>Table of contents</summary>

• Quickstart
  • Installing assemble
  • Installing assemble's CLI
  • assemblefile.js
• CLI
  • Running tasks
  • Specifying options
  • Object expansion
• Command line options
  • cwd
  • file
• API
  • Templates API
    • .create
    • View types
    • .engine
    • .render
  • File System API
    • .src
    • .dest
    • .copy
    • .renderFile
  • Task API
    • .task
    • .build
    • .watch
• Plugins
  • Discovering plugins
  • Authoring plugins
• Learning
  • Help
  • More information
  • FAQ
• About
  • Community
  • Related projects
  • Similar projects
  • Release history
  • Contributing
  • Contributors
  • Authors
  • License

(TOC generated by verb using markdown-toc)

</details> <details> <summary>What is Assemble?</summary>

Assemble is a command line tool and developer framework for rapid prototyping, static site generation, and much more.

</details> <details> <summary>Who uses assemble?</summary>

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
• Diebold
• Transformicons
• Barrel
• yesware
• Amaze
• sennheiser
• perf.rocks
• Milano JS
• AKQA
• huxtaburger
• Typeplate
• Angular Basics

Is your website, blog or project built with assemble? Please let us know about it!

</details> <details> <summary>Why should I use assemble?</summary>

• 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 plugin
• Powerful features for rapid web development, including a robust API for rendering templates with any node.js template engine.
• Assemble can use any 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.

</details> <details> <summary>What can I do with Assemble?</summary>

• Rapid prototyping
• Static site generation (more powerful alternative to jekyll)
• Landing pages
• A/B testing
• blogs
• Styleguides
• Themes
• UI components
• Project scaffolder (generate is also built on assemble)
• build tool
• Documentation (verb is built on assemble)
• Generate boilerplates, scaffolds, and targets
• E-books (Angular Basics was built with assemble)
• Much more!

</details> <details> <summary>Rapid development toolkit</summary>

Assemble can be used standalone, but it's even more powerful when used alongside the following libraries:

• generate: scaffold out new projects from the command line
• assemble: <= you are here
• verb: generate documention for your projects
• update: keep your projects up-to-date

</details> <details> <summary>Features</summary>

Here are just a few of the features assemble offers:

• Intuitive CLI
• Full support for gulp and base plugins
• Assemble templates are vinyl files
• Render templates with any template engine, including nunjucks, handlebars, lodash and any consolidate engine!
• Use multiple engines, assemble can detect the one to use based on file extension
• helpers: support for sync and async
• Templates collections
• Pages
• Partials/includes
• Layouts
• Pagination
• permalinks
• middleware can be used to tranform files at any stage in the render cycle
• Generate pages from JSON
• Much more!

</details>

Quickstart

Installing assemble

Add assemble your project's devDependencies using npm:

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

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

Then run

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

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

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

$ 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](#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:

<img width="527" alt="screen shot 2016-01-09 at 1 35 52 pm" src="https://cloud.githubusercontent.com/assets/383994/12217685/0a14294e-b6d6-11e5-9e06-dc4738f0e53a.png">

file

Specify the name of the config file for assemble's CLI to run, the default is assemblefile.js.

**Example