Get the rocks out of your socks! Assemble makes you fast at web development! Used by thousands of projects for rapid prototyping, themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites/static site generator, an alternative to Jekyll for gh-pages and more! Gulp- and grunt-friendly.
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).
(Click the following sections to expand them)
(TOC generated by verb using markdown-toc)
Assemble is a command line tool and developer framework for rapid prototyping, static site generation, and much more.
Assemble is used by thousands of developers and teams in more than 170 countries! Here are a few examples of sites built with assemble:
Is your website, blog or project built with assemble? Please let us know about it!
Assemble can be used standalone, but it's even more powerful when used alongside the following libraries:
Here are just a few of the features assemble offers:
Add assemble your project's
devDependenciesusing npm:
$ npm install -D assemble
You should now be able to run assemble directly (using
node assemblefile.jsetc) or using
npmscripts. For example, add the following to package.json:
{ "scripts": { "build": "assemble" } }
Then run
$ npm run build
You can also assemble's CLI globally, which adds the
assemblecommand 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.
To use assemble's CLI, you'll need to add an
assemblefile.jsto your project. The fastest way to do this is to run the following command:
$ assemble
If no
assemblefile.jsexists in the current project, assemble will ask if you want to add one. If you answer yes, assemble will then generate a basic
assembfile.jsfor you.
Run assemble from the command line.
$ assemble [options]
Specify one or more space-separated tasks to run.
Examples
Run task
foo
$ assemble foo
Run tasks
fooand
bar
$ assemble foo bar
Non-task options are prefixed with
--.
Examples
Set the
--cwdto 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-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
cwdfor the
assemblefile.jsto run, optionally specifying any tasks to run:
$ assemble --cwd [directory]
Example
To run the
scaffoldsexample in the
examples/directory, you would enter:
$ assemble --cwd examples/scaffolds
If successful, in the command line, you should see something like this:
Specify the name of the config file for assemble's CLI to run, the default is
assemblefile.js.
Example
$ assemble --file assemblefile.dev.js
Create an
assembleapp. 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();
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
contentproperty that contains the template string. Since views are instances of vinyl, you can think of a view as a "vinyl file for templates".
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 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
renderableview 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
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,
localsand
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
withlocals
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
hbsengine to render all templates:
app.src('templates/*.*') .pipe(app.renderFile('hbs'))
Render a view with the given
localsand
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}
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
srcplugins
Example
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
destplugins
Example
app.dest('dist/');
Copy files with the given glob
patternsto 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/'); });
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'));
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 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/')); });
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 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 from any applications built on base should work with Assemble and can be used in your
assemblefile.js:
basepluginkeyword
assemblepluginkeyword
generatepluginkeyword
templatespluginkeyword
updatepluginkeyword
verbpluginkeyword
Visit the plugin documentation guide to learn how to use, author and publish plugins.
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!
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, and
partials, middleware for parsing front-matter, and a few other basic defaults that we've found many users expect. If you'd prefer different defaults, assemble-core is a great starting point.
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
.srcand
.destmethods have built-in
.onStream,
.preWrite, and
.postWritemiddleware handlers. If you still wish to use gulp and your build cycle includes middleware that requires these handlers, you can use the assemble-handle plugin with gulp to ensure that the handlers are still called as needed.
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.
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
@assemblejsor use the
#assemblehashtag
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
assembletag in questions)
Gitter Discuss Assemble with us on Gitter
For maximum discoverability, plugin developers should use the keyword
assemblepluginon 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.
You might also be interested in these projects from @doowb and @jonschlinkert:
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
Blog frameworks
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.
added
fixed
isbinaryfilewas trying to read from a file that didn't exist.
dependencies
viewis decorated with
.toStream()when created by
app(versus a collection).
dependencies
fixed
view.statto be null in some cases after
view.pathchanged
view.basewas not always correct on views that were not created from the file system
dependencies
desthandling
dependencies
lists
Dependencies
Dependencies
.log()method, which also exposes additional methods, like
.log.info(),
.log.success(), etc.
support/docs, so that markdown docs can be built to the
docsdirectory
renameKeyoption from the
.datamethod. Use the
namespaceoption instead.
Bumps assemble-core to v0.22.0 to take advantage of fixes and improvements to lookup methods:
.findand
getView. No API changes were made. Please let us know if regressions occur.
Listbug that was caused collection helpers to explode
app.getView()and
app.find()
queueproperty was removed on collections. See assemble-core for additional details.
file.base, causing dest directory to be relative to cwd instead of glob parent in some cases.
renameKeyto not always be used when defined on collection loader options.
debugmethods and related code have been removed
node_modulesand reinstall all dependencies to avoid errors such as
isRegistered is not a function
.watchmethod in favor of using the base-watch plugin.
(Changelog generated by helper-changelog)
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
| 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 |
Jon Schlinkert
Brian Woodward
Copyright © 2017, Jon Schlinkert. MIT
This file was generated by verb-generate-readme, v0.6.0, on December 27, 2017.