Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit
Welcome to Assemble v0.16.2!
Assemble is a command line tool and developer framework for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites / static site generator, alternative to jekyll for gh-pages and more!
(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).
Assemble is used by thousands of projects, including:
Assemble can be used to create:
Project lifecycle
As a standalone library, assemble can be used for creating, building and maintaining entire web projects. But it's even more powerful when used longside the following libraries:
Assemble also has a grunt plugin and can be used alongside gulp.
Features
(TOC generated by verb using markdown-toc)
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.
Render a template with with handlebars:
var assemble = require('assemble');
var app = assemble();
var locals = {title: 'Home!'};
// add a "page"
app.page('home.hbs', {content: 'This is '});
// render it!
app.render('home.hbs', locals, function(err, view) {
if (err) throw err;
console.log(view.content);
//=> 'This is Home!'
});
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;
Run assemble from the command line.
$ assemble <tasks> [options]
Specify one or more space-separated tasks to run.
Examples
Run task foo
$ assemble foo
Run tasks foo and bar
$ assemble foo bar
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-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 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:
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 assemble app. 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.
Create a template collection.
app.create('includes');
Add views to the collection.
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 src pluginsExample
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 dest pluginsExample
app.dest('dist/');
Copy files with the given glob patterns to 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/');
});
Same as .src but takes glob patterns or filepaths for the symlinks to read.
Params
glob {String|Array}: Glob patterns or file pathsExample
app.symlink('src/*.hbs');
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 namefn {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 errExample
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:
baseplugin keywordassembleplugin keywordgenerateplugin keywordtemplatesplugin keywordupdateplugin keywordverbplugin keywordVisit 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 .src and .dest methods have built-in .onStream, .preWrite, and .postWrite middleware 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.
Are you using assemble in your project? Have you published an assemble project and want to share your project with the world?
Here are some suggestions!
@assemble or use the #assemble hashtagassembleassemble tag in questions)assembleplugin to package.json.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 featureschanged: for changes in existing functionalitydeprecated: for once-stable features removed in upcoming releasesremoved: for deprecated features removed in this releasefixed: for any bug fixesCustom labels used in this changelog:
dependencies: bumps dependencieshousekeeping: code re-organization, minor edits, or other changes that don't fit in one of the other categories.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 docs directoryrenameKey option from the .data method. Use the namespace option instead.Bumps assemble-core to v0.22.0 to take advantage of fixes and improvements to lookup methods: .find and getView. No API changes were made. Please let us know if regressions occur.
List bug that was caused collection helpers to explodeapp.getView() and app.find()queue property 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.renameKey to not always be used when defined on collection loader options.debug methods and related code have been removednode_modules and reinstall all dependencies to avoid errors such as isRegistered is not a function.watch method in favor of using the base-watch plugin.Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for avice on opening issues, pull requests, and coding standards.
If Assemble doesn't do what you need, please let us know
Jon Schlinkert
Brian Woodward
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb-generate-readme, v0.1.28, on August 06, 2016.
[0.17.0]
Dependencies
FAQs
Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit
The npm package assemble receives a total of 2,863 weekly downloads. As such, assemble popularity was classified as popular.
We found that assemble demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISA’s 2024 report highlights the EU’s top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.
Security News
NIST's new password guidelines remove periodic changes and special character requirements, focusing on longer, more secure passwords for better authentication practices.