Looking for the grunt plugin? Please visitgrunt-assemble.
(Note that the current website assemble.io, is forgrunt-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)
Table of contents
(TOC generated byverbusingmarkdown-toc)
What is Assemble?
Assemble is a command line tool and developer framework for rapid prototyping, static site generation, andmuch more.
Who uses assemble?
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? Pleaselet us know about it!
Why should I use assemble?
- 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 anygulpplugin
- Powerful featuresfor rapid web development, including a robust API for rendering templates with any node.js template engine.
- Assemble can use anybaseplugin
- Assemble can do anything Jekyll does, but with more flexibility and control
- Like gulp, assemble can also runanyother 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.
What can I do with Assemble?
- Rapid prototyping
- Static site generation (more powerful alternative to jekyll)
- Landing pages
- A/B testing
- blogs
- Styleguides
- Themes
- UI components
- Project scaffolder(generateis also built on assemble)
- build tool
- Documentation (verbis built on assemble)
- Generateboilerplates,scaffolds,andtargets
- E-books (Angular Basicswas built with assemble)
- Much more!
Rapid development toolkit
Assemble can be used standalone, but it's even more powerful when used alongside the following libraries:
Features
Here are just a few of the features assemble offers:
- Intuitive CLI
- Full support forgulpandbaseplugins
- Assemble templates arevinylfiles
- Render templates with anytemplate engine,includingnunjucks,handlebars,lodashand 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
- middlewarecan be used to tranform files at any stage in the render cycle
- Generate pages from JSON
- Much more!
Add assemble your project'sdevDependenciesusingnpm:
$ npm install -D assembleYou should now be able to run assemble directly (usingnode assemblefile.jsetc) or usingnpmscripts. For example, add the following to package.json:
{
"scripts":{
"build":"assemble"
}
}Then run
$ npm run buildYou can also assemble's CLI globally, which adds theassemblecommand to your system path, allowing it to be run from any directory.
$ npm install --global assembleNote 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 anassemblefile.jsto your project. The fastest way to do this is to run the following command:
$ assembleIf noassemblefile.jsexists in the current project, assemble will ask if you want to add one. If you answer yes, assemble will then generate a basicassembfile.jsfor you.
Run assemble from the command line.
$ assemble<tasks>[options]Specify one or more space-separated tasks to run.
Examples
Run taskfoo
$ assemble fooRun tasksfooandbar
$ assemble foo barNon-task options are prefixed with--.
Examples
Set the--cwdto run an assemblefile.js in a different directory:
$ assemble --cwd=docsEmit views as they're loaded and log them tostderr:
$ assemble --emit=viewSee more [command line options](#command line options)
Object-paths may be specified using dot-notation foreither the key or valuein a command line argument.
Additionally, assemble usesexpand-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 thecwdfor theassemblefile.jsto run, optionally specifying any tasks to run:
$ assemble<tasks>--cwd [directory]Example
To run thescaffoldsexample in theexamples/directory, you would enter:
$ assemble --cwd examples/scaffoldsIf 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 isassemblefile.js.
Example
$ assemble --file assemblefile.dev.jsCreate anassembleapp. This is the main function exported by the assemble module.
Params
options{Object}:Optionally pass default options to use.
Example
varassemble=require('assemble');
varapp=assemble();Assemble exposes the entire API from thetemplateslibrary for working with templates and template collections. The API is much more extensive than what is documented here, seetemplatesfor more documentation.
Templates and Views
In the following documentation, the terms "template" and "view" both refer toaspectsof the same thing. Here's what they mean:
template:an actual template stringview:a object with acontentproperty that contains the template string. Since views are instances ofvinyl,you can think of a view as a "vinyl file for templates".
Create a template collection for cachingviews:
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 moreview typesto associate with the collection
Add views
Add a view to the collection:
app.include('foo.md',{contents:newBuffer('this is contents')});Add multiple views:
app.includes({
path:'foo.md',contents:newBuffer('this is contents'),
path:'bar.md',contents:newBuffer('this is contents'),
path:'baz.md',contents:newBuffer('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. Therenderableview 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 arrayRegister template engine for rendering views with the givenext:
app.engine(ext,fn);Params
ext{String}:The file extension of files to render with the enginefn{Function}:Async function that followsconsolidateengine conventions, and takes three arguments:str,localsandcallback.
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 onoptions.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 thehbsengine to render all templates:
app.src('templates/*.*')
.pipe(app.renderFile('hbs'))Render a view with the givenlocalsandcallback.
app.render(view,{title:'Foo'},function(err,view){
// `view` is an object with a rendered `content` property
});Params
view{Object|String}:The view to renderlocals{Object}:Locals to pass to template engine for rendering templates inviewcallback{Function}
Assemble offers the following low-level methods for working with the file system:
Assemble has first-class support forvinyl-fs,so anygulpplugin can be used in your assemble pipeline.
Create avinylstream. 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 tosrcplugins
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 todestplugins
Example
app.dest('dist/');Copy files with the given globpatternsto the specifieddest.
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
returnapp.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 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 exposeserr
Example
app.build(['foo','bar'],function(err){
if(err)throwerr;
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 onbaseshould work with Assemble and can be used in yourassemblefile.js:
- base:find base plugins on npm using the
basepluginkeyword - assemble:find assemble plugins on npm using the
assemblepluginkeyword - generate:find generate plugins on npm using the
generatepluginkeyword - templates:find templates plugins on npm using the
templatespluginkeyword - update:find update plugins on npm using the
updatepluginkeyword - verb:find verb plugins on npm using the
verbpluginkeyword
Visit theplugin documentationguide to learn how to use, author and publish plugins.
Get in touch!
Have questions, suggestions, or want to discuss assemble? Join the conversation ongitteror give us a shout ontwitter.The assemble team and community are always happy to help!
Documentation(Temporarily, while we work on the new website, docs can be found insupport/docs/src)- API documentation
- Generators maintained by the core team
Website is outdated and being refactored!
Assemble's website, assemble.io, only has information related togulp-assemble.We're working hard to update the site with information about the latest release.
In the meantime, you might find theWIP docsuseful. Theunit testsare also great examples!
Is the assemble website up-to-date?
No, as mentioned above, it's completely out-of-date. If you're usinggrunt-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 betweenassemble-coreand assemble?
Assemble adds a CLI, a few built-in view collections:pages,layouts,andpartials,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-coreis 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 usingtemplatesinstead 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 theassemble-handleplugin 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 ourgulp FAQfor 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 toThe Official Assemble Blog.
-
Join theconversation on Gitter
-
Tell us aboutyour assemble project
-
Show your love by starring Assemble!
-
Get implementation help onStackOverflow(please use theassemble
assembletag in questions) -
GitterDiscuss Assemble with us onGitter
-
For maximum discoverability, plugin developers should use the keyword
assemblepluginon packages which modify or add to the functionality of Assemble when distributing throughnpmor similar delivery mechanisms.
Contributing
Please read ourcontributing guideif you'd like to learn more about contributing to this project.
You might also be interested in these projects from@doowband@jonschlinkert:
- boilerplate:Tools and conventions for authoring and using declarative configurations for project "boilerplates" that can be…more| [homepage](https://github /jonschlinkert/boilerplate"Tools and conventions for authoring and using declarative configurations for project" boilerplates "that can be consumed by any build system or project scaffolding tool." )
- 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
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 Alpha betical order):
Static site generators
Blog frameworks
Changelog entries are classified using the following labels(fromkeep-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 fixes
Custom 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.
0.24.0- 2017-05-19
added
- By popular request, assemble now automatically expands config templates in yaml front-matter, viaexpand-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 useis-binary-buffer,which fixes a bug where
isbinaryfilewas trying to read from a file that didn't exist.
0.23.0- 2017-02-11
dependencies
- Bumpsassemble-coreto get an update toassemble-streamsthat ensures that
viewis decorated with.toStream()when created byapp(versus a collection).
0.21.0- 2017-02-03
dependencies
- Bumpsassemble-loaderto 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.statto be null in some cases afterview.pathchanged view.basewas not always correct on views that were not created from the file system
0.20.0- 2017-02-02
dependencies
- Bumpsassemble-coreto v0.29.0 to take advantage of improvements to
desthandling
0.19.0- 2017-02-01
dependencies
- Bumpsassemble-coreto v0.28.0 to take advantage of new methods available on
lists
Dependencies
- bumpsassemble-coreto 0.27.0
Dependencies
- bumpsassemble-coreto 0.26.0
- bump dependencies. In particular, there was a bug inparser-front-matterwhere leading whitespace was removed after extracting front-matter, which caused the first line of indentation to be removed. This has been fixed.
- 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 thedocsdirectory - docs were updated, new docs added
- Moves some private prototype methods to static methods, to allow them to be used without creating an instance
- Bumpsassemble-coreto v0.25.0
- Bumpsassemble-coreto v0.24.0 to get the latest versions oftemplatesandbase-datawhich removes the
renameKeyoption from the.datamethod. Use thenamespaceoption instead.
Bumpsassemble-coreto v0.22.0 to take advantage of fixes and improvements to lookup methods:.findandgetView.No API changes were made. Pleaselet us knowif regressions occur.
- fixes
Listbug that was caused collection helpers to explode - Improvements to lookup functions:
app.getView()andapp.find() - Bumpsbaseto take advantages of code optimizations.
- Bumpsassemble-coreto v0.21.0. Support for the
queueproperty was removed on collections. Seeassemble-corefor 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 commontemplatestests to base-test-runner, so that assemble plugins and otherbaseapplications can use the tests
- Includes a fix fromassemble-loader,where a bug caused
renameKeyto not always be used when defined on collection loader options. - Includes fixes from templates for resolving layouts
- Bumpsassemble-coreto v0.18.0, which includes a bump intemplates.See the changelog on the templates library for more details.
debugmethods and related code have been removed- Bumpsassemble-coreto v0.17.0
- Adds support for using es6 generators with tasks
- Bumpsassemble-coreto v0.15.0
- Bumps several dependencies. No API changes, this is mostly an optimization release. Be sure to completely remove
node_modulesand reinstall all dependencies to avoid errors such asisRegistered is not a function
- Updatescomposerto v0.11.0, which removes the
.watchmethod in favor of using thebase-watchplugin. - Changes intemplates.Please see v0.11.0 intemplates historyfor more details.
- Stability improvements and optimizations of the API introduced in v0.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 togrunt-assemble.Please see that repo for additional details.
(Changelog generated byhelper-changelog)
Pull requests and stars are always welcome. For bugs and feature requests,please create an issue.
Please read thecontributing guidefor 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 byverb-generate-readme,v0.6.0, on December 27, 2017.
