{"id":13397283,"url":"https://github.com/assemble/assemble","last_synced_at":"2025-05-14T00:06:43.062Z","repository":{"id":4765946,"uuid":"5916767","full_name":"assemble/assemble","owner":"assemble","description":"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.  ","archived":false,"fork":false,"pushed_at":"2022-02-20T09:16:14.000Z","size":13050,"stargazers_count":4256,"open_issues_count":28,"forks_count":279,"subscribers_count":106,"default_branch":"master","last_synced_at":"2025-04-10T02:16:54.423Z","etag":null,"topics":["assemble","blog-engine","build","css","docs","documentation","generator","grunt","gulp","html","html-templates","javascript","markdown","md","nodejs","pwa","scaffold","static-site","static-site-generator","templates"],"latest_commit_sha":null,"homepage":"http://assemble.io/","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/assemble.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-22T20:50:23.000Z","updated_at":"2025-04-09T07:35:40.000Z","dependencies_parsed_at":"2022-07-07T01:02:28.196Z","dependency_job_id":null,"html_url":"https://github.com/assemble/assemble","commit_stats":null,"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assemble%2Fassemble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assemble%2Fassemble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assemble%2Fassemble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assemble%2Fassemble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/assemble","download_url":"https://codeload.github.com/assemble/assemble/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248142907,"owners_count":21054672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assemble","blog-engine","build","css","docs","documentation","generator","grunt","gulp","html","html-templates","javascript","markdown","md","nodejs","pwa","scaffold","static-site","static-site-generator","templates"],"created_at":"2024-07-30T18:01:15.152Z","updated_at":"2025-04-10T02:17:01.323Z","avatar_url":"https://github.com/assemble.png","language":"CSS","readme":"\u003cp align=\"center\"\u003e\n\n\u003ca href=\"https://github.com/assemble/assemble\"\u003e\n\u003cimg height=\"250\" width=\"250\" src=\"https://raw.githubusercontent.com/assemble/assemble/master/docs/logo.png\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n# assemble\n\n[![NPM version](https://img.shields.io/npm/v/assemble.svg?style=flat)](https://www.npmjs.com/package/assemble) [![NPM monthly downloads](https://img.shields.io/npm/dm/assemble.svg?style=flat)](https://npmjs.org/package/assemble) [![Build Status](https://img.shields.io/travis/assemble/assemble.svg?style=flat)](https://travis-ci.org/assemble/assemble) [![Gitter](https://badges.gitter.im/join_chat.svg)](https://gitter.im/assemble/assemble)\n\nLooking for the grunt plugin? Please visit [grunt-assemble](https://github.com/assemble/grunt-assemble).\n\n_(Note that the current website assemble.io, is for [grunt-assemble](https://github.com/assemble/grunt-assemble). Thanks for your patience while we work on updating the site with documentation for the latest assemble)_.\n\n## Overview\n\n_(Click the following sections to expand them)_\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of contents\u003c/summary\u003e\n\n- [Quickstart](#quickstart)\n  * [Installing assemble](#installing-assemble)\n  * [Installing assemble's CLI](#installing-assembles-cli)\n  * [assemblefile.js](#assemblefilejs)\n- [CLI](#cli)\n  * [Running tasks](#running-tasks)\n  * [Specifying options](#specifying-options)\n  * [Object expansion](#object-expansion)\n- [Command line options](#command-line-options)\n  * [cwd](#cwd)\n  * [file](#file)\n- [API](#api)\n  * [Templates API](#templates-api)\n    + [.create](#create)\n    + [View types](#view-types)\n    + [.engine](#engine)\n    + [.render](#render)\n  * [File System API](#file-system-api)\n    + [.src](#src)\n    + [.dest](#dest)\n    + [.copy](#copy)\n    + [.renderFile](#renderfile)\n  * [Task API](#task-api)\n    + [.task](#task)\n    + [.build](#build)\n    + [.watch](#watch)\n- [Plugins](#plugins)\n  * [Discovering plugins](#discovering-plugins)\n  * [Authoring plugins](#authoring-plugins)\n- [Learning](#learning)\n  * [Help](#help)\n  * [More information](#more-information)\n  * [FAQ](#faq)\n- [About](#about)\n  * [Community](#community)\n  * [Related projects](#related-projects)\n  * [Similar projects](#similar-projects)\n  * [Release history](#release-history)\n  * [Contributing](#contributing)\n  * [Contributors](#contributors)\n  * [Authors](#authors)\n  * [License](#license)\n\n_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWhat is Assemble?\u003c/summary\u003e\n\nAssemble is a command line tool and developer framework for rapid prototyping, static site generation, and [much more](#what-can-i-do-with-assemble).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWho uses assemble?\u003c/summary\u003e\n\nAssemble is used by thousands of developers and teams in more than 170 countries! Here are a few examples of sites built with assemble:\n\n* [Airbus Group](http://www.airbusgroup.com/int/en.html)\n* [Diebold](http://www.diebold.com/)\n* [Transformicons](http://www.transformicons.com/)\n* [Barrel](https://www.barrelny.com/)\n* [yesware](https://www.yesware.com/)\n* [Amaze](https://www.amaze.com/)\n* [sennheiser](http://sennheiser-d1.com/)\n* [perf.rocks](http://perf.rocks/)\n* [Milano JS](http://milanojs.com/)\n* [AKQA](http://www.akqa.com/)\n* [huxtaburger](http://www.huxtaburger.com.au/)\n* [Typeplate](http://typeplate.com/)\n* [Angular Basics](http://www.angularjsbook.com/)\n\nIs your website, blog or project built with assemble? Please [let us know about it](../../issues/300)!\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWhy should I use assemble?\u003c/summary\u003e\n\n* Expressive, functional API (the API is also stable)\n* You can use assemble with any web framework or CSS/HTML toolkit\n* Assemble can build static sites or hybrid static/dynamic sites\n* Streams support, you can run any [gulp](http://gulpjs.com) plugin\n* [Powerful features](#features) for rapid web development, including a robust API for rendering templates with any node.js template engine.\n* Assemble can use any [base](https://github.com/node-base/base) plugin\n* Assemble can do anything Jekyll does, but with more flexibility and control\n* 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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWhat can I do with Assemble?\u003c/summary\u003e\n\n* Rapid prototyping\n* Static site generation (more powerful alternative to jekyll)\n* Landing pages\n* A/B testing\n* [blogs](examples/blog)\n* Styleguides\n* Themes\n* UI components\n* [Project scaffolder](examples/generator) ([generate](https://github.com/generate/generate) is also built on assemble)\n* [build tool](examples/build-tool)\n* Documentation ([verb](https://github.com/verbose/verb) is built on assemble)\n* Generate [boilerplates](examples/boilerplates), [scaffolds](examples/scaffold), and [targets](examples/targets)\n* E-books ([Angular Basics](http://www.angularjsbook.com/) was built with assemble)\n* Much more!\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRapid development toolkit\u003c/summary\u003e\n\nAssemble can be used standalone, but it's even more powerful when used alongside the following libraries:\n\n* [generate](https://github.com/generate/generate): scaffold out new projects from the command line\n* [assemble](https://github.com/assemble/): \u003c= you are here\n* [verb](https://github.com/verbose/verb): generate documention for your projects\n* [update](https://github.com/update/update): keep your projects up-to-date\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFeatures\u003c/summary\u003e\n\nHere are just a few of the features assemble offers:\n\n* Intuitive CLI\n* Full support for [gulp](http://gulpjs.com) and [base](https://github.com/node-base/base) plugins\n* Assemble templates are [vinyl](https://github.com/gulpjs/vinyl) files\n* Render templates with any [template engine](#engine), including [nunjucks](https://github.com/assemble/assemble-nunjucks), [handlebars](https://github.com/jonschlinkert/engine-handlebars), [lodash](https://github.com/jonschlinkert/engine-lodash) and any consolidate engine!\n* Use multiple engines, assemble can detect the one to use based on file extension\n* [helpers](#helpers): support for sync and async\n* [Templates collections](#collections)\n* Pages\n* Partials/includes\n* [Layouts](https://github.com/doowb/layouts)\n* Pagination\n* [permalinks](https://github.com/assemble/assemble-permalinks)\n* [middleware](#middleware) can be used to tranform files at any stage in the render cycle\n* Generate pages from JSON\n* Much more!\n\n\u003c/details\u003e\n\n## Quickstart\n\n### Installing assemble\n\nAdd assemble your project's `devDependencies` using [npm](https://npmjs.org):\n\n```sh\n$ npm install -D assemble\n```\n\nYou 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:\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"assemble\"\n  }\n}\n```\n\nThen run\n\n```sh\n$ npm run build\n```\n\n### Installing assemble's CLI\n\nYou can also assemble's CLI globally, which adds the `assemble` command to your system path, allowing it to be run from any directory.\n\n```sh\n$ npm install --global assemble\n```\n\n_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._\n\n### assemblefile.js\n\nTo 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:\n\n```sh\n$ assemble\n```\n\nIf 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.\n\n## CLI\n\nRun assemble from the command line.\n\n```sh\n$ assemble \u003ctasks\u003e [options]\n```\n\n### Running tasks\n\nSpecify one or more space-separated tasks to run.\n\n**Examples**\n\nRun task `foo`\n\n```sh\n$ assemble foo\n```\n\nRun tasks `foo` and `bar`\n\n```sh\n$ assemble foo bar\n```\n\n### Specifying options\n\nNon-task options are prefixed with `--`.\n\n**Examples**\n\nSet the `--cwd` to run an assemblefile.js in a different directory:\n\n```sh\n$ assemble --cwd=docs\n```\n\nEmit views as they're loaded and log them to `stderr`:\n\n```sh\n$ assemble --emit=view\n```\n\nSee more [command line options](#command line options)\n\n### Object expansion\n\nObject-paths may be specified using dot-notation for **either the key or value** in a command line argument.\n\nAdditionally, assemble uses [expand-object](https://github.com/jonschlinkert/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.\n\n**Examples**\n\nBoolean values:\n\n```sh\n$ assemble --foo \n# { foo: true }\n```\n\nKey-value pairs:\n\n```sh\n$ assemble --foo=bar\n# { foo: 'bar' }\n```\n\nNested booleans:\n\n```sh\n$ assemble --option=foo \n# {options: { foo: true }}\n```\n\nNested key-value pairs:\n\n```sh\n$ assemble --option=foo:bar\n# {options: { foo: 'bar' }}\n```\n\nDeeply nested key-value pairs:\n\n```sh\n$ assemble --option=foo.bar.baz:qux\n# {options: foo: { bar: { baz: 'qux' }}}}\n```\n\nOr on the left-side of the `=`:\n\n```sh\n$ assemble --option.foo.bar.baz=qux\n# {options: foo: { bar: { baz: 'qux' }}}}\n```\n\n## Command line options\n\n### cwd\n\nChange the `cwd` for the `assemblefile.js` to run, optionally specifying any tasks to run:\n\n```sh\n$ assemble \u003ctasks\u003e --cwd [directory]\n```\n\n**Example**\n\nTo run the `scaffolds` example in the `examples/` directory, you would enter:\n\n```sh\n$ assemble --cwd examples/scaffolds\n```\n\nIf successful, in the command line, you should see something like this:\n\n\u003cimg 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\"\u003e\n\n### file\n\nSpecify the name of the config file for assemble's CLI to run, the default is `assemblefile.js`.\n\n**Example**\n\n```sh\n$ assemble --file assemblefile.dev.js\n```\n\n## API\n\n### [Assemble](index.js#L24)\n\nCreate an `assemble` app. This is the main function exported by the assemble module.\n\n**Params**\n\n* `options` **{Object}**: Optionally pass default options to use.\n\n**Example**\n\n```js\nvar assemble = require('assemble');\nvar app = assemble();\n```\n\n### Templates API\n\nAssemble exposes the entire API from the [templates](https://github.com/jonschlinkert/templates) library for working with templates and template collections. The API is much more extensive than what is documented here, see [templates](https://github.com/jonschlinkert/templates) for more documentation.\n\n**Templates and Views**\n\nIn the following documentation, the terms \"template\" and \"view\" both refer to _aspects_ of the same thing. Here's what they mean:\n\n* `template`: an actual template string\n* `view`: a object with a `content` property that contains the template string. Since views are instances of [vinyl](https://github.com/gulpjs/vinyl), you can think of a view as a \"vinyl file for templates\".\n\n#### .create\n\nCreate a template collection for caching [views](https://github.com/cpsubrian/node-views):\n\n```js\napp.create('includes', {viewType: 'partial'});\n```\n\n**Options**\n\n* `cwd` **{String}**: the base directory to use when loading templates onto the collection from a glob\n\n* `viewType`: **{String|Array}**: One or more [view types](#view-types) to associate with the collection\n\n**Add views**\n\nAdd a view to the collection:\n\n```js\napp.include('foo.md', {contents: new Buffer('this is contents')});\n```\n\nAdd multiple views:\n\n```js\napp.includes({\n  path: 'foo.md', contents: new Buffer('this is contents'),\n  path: 'bar.md', contents: new Buffer('this is contents'),\n  path: 'baz.md', contents: new Buffer('this is contents')\n});\n\n// or pass a glob (optionally override `cwd` defined on `.create`)\napp.includes('*.{md,hbs}', {cwd: 'templates/includes'});\n```\n\n#### View types\n\nView types are defined on a collection to determine how a templates in the collection will be handled throughout the [render cycle][].\n\n**Available types**\n\nAssemble supports three view types:\n\n* `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.\n* `layout`: allows views to \"wrap\" other views (of any type, including other layouts or partials) with common code or content.\n* `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.\n\n**Defining view types**\n\nYou can define view types when a collection is created:\n\n```js\napp.create('snippet', {viewType: 'partial'});\n```\n\nOr directly on the collection options:\n\n```js\napp.create('snippet');\napp.snippets.option('viewType', ['partial']); // string or array\n```\n\n#### .engine\n\nRegister template engine for rendering views with the given `ext`:\n\n```js\napp.engine(ext, fn);\n```\n\n**Params**\n\n* `ext` **{String}**: The file extension of files to render with the engine\n* `fn` **{Function}**: Async function that follows [consolidate](https://github.com/visionmedia/consolidate.js) engine conventions, and takes three arguments: `str`, `locals` and `callback`.\n\n**Example**\n\n```js\n// this engine is already registered in assemble\napp.engine('hbs', require('engine-handlebars'));\n\n// create a custom engine\napp.engine('txt', function(str, locals, cb) {\n  // render `str` with `locals`\n  cb(null, str);\n});\n```\n\nYou can tell assemble to use the same engine for all file extensions by setting a value on `options.engine`.\n\n**Example**\n\n```js\n// use engine `hbs` for rendering all files\napp.option('engine', 'hbs');\n```\n\nOr, if you're using [.renderFile](#renderFile), you can force a specific engine to be used by passing the engine name.\n\n**Example**\n\nUse the `hbs` engine to render all templates:\n\n```js\napp.src('templates/*.*')\n  .pipe(app.renderFile('hbs'))\n```\n\n#### .render\n\nRender a view with the given `locals` and `callback`.\n\n```js\napp.render(view, {title: 'Foo'}, function(err, view) {\n  // `view` is an object with a rendered `content` property\n});\n```\n\n**Params**\n\n* `view` **{Object|String}**: The view to render\n* `locals` **{Object}**: Locals to pass to template engine for rendering templates in `view`\n* `callback` **{Function}**\n\n***\n\n### File System API\n\nAssemble offers the following low-level methods for working with the file system:\n\n* [src](#src)\n* [symlink](#symlink)\n* [dest](#dest)\n* [copy](#copy)\n\nAssemble has first-class support for [vinyl-fs](https://github.com/gulpjs/vinyl-fs), so any [gulp](http://gulpjs.com) plugin can be used in your assemble pipeline.\n\n#### .src\n\nCreate a [vinyl](https://github.com/gulpjs/vinyl) stream. Takes glob patterns or filepaths to the source files to read.\n\n**Params**\n\n* `glob` **{String|Array}**: Glob patterns or file paths to source files.\n* `options` **{Object}**: Options or locals to merge into the context and/or pass to `src` plugins\n\n**Example**\n\n```js\napp.src('src/*.hbs');\n\n// define `src` options\napp.src('src/*.hbs', { layout: 'default' });\n```\n\n#### .dest\n\nSpecify a destination for processed files.\n\n**Params**\n\n* `dest` **{String|Function}**: File path or rename function.\n* `options` **{Object}**: Options and locals to pass to `dest` plugins\n\n**Example**\n\n```js\napp.dest('dist/');\n```\n\n#### .copy\n\nCopy files with the given glob `patterns` to the specified `dest`.\n\n**Params**\n\n* `patterns` **{String|Array}**: Glob patterns of files to copy.\n* `dest` **{String|Function}**: Desination directory.\n* `returns` **{Stream}**: Stream, to continue processing if necessary.\n\n**Example**\n\n```js\napp.task('assets', function() {\n  // return, to let assemble know when the task has completed\n  return app.copy('assets/**', 'dist/');\n});\n```\n\n#### .renderFile\n\nRenders files as they are pushed through the stream.\n\n```js\napp.src('*.hbs')\n  .pipe(app.renderfile())\n  .pipe(app.dest('foo'));\n```\n\nForce a specific engine to be used for rendering files:\n\n```js\napp.engine('txt', function(str, locals, cb) {\n  cb(null, str);\n});\n\napp.src('*.hbs')\n  .pipe(app.renderfile('txt')) //\u003c= use engine `txt`\n  .pipe(app.dest('foo'));\n```\n\n***\n\n### Task API\n\nAssemble has the following methods for running tasks and controlling workflows:\n\n* [task](#task)\n* [build](#build)\n* [watch](#watch)\n\n#### .task\n\nDefine a task to be run when the task is called.\n\n**Params**\n\n* `name` **{String}**: Task name\n* `fn` **{Function}**: function that is called when the task is run.\n\n**Example**\n\n```js\napp.task('default', function() {\n  app.src('templates/*.hbs')\n    .pipe(app.dest('site/'));\n});\n```\n\n#### .build\n\nRun one or more tasks.\n\n**Params**\n\n* `tasks` **{Array|String}**: Task name or array of task names.\n* `cb` **{Function}**: callback function that exposes `err`\n\n**Example**\n\n```js\napp.build(['foo', 'bar'], function(err) {\n  if (err) throw err;\n  console.log('done!');\n});\n```\n\n#### .watch\n\nWatch files, run one or more tasks when a watched file changes.\n\n**Params**\n\n* `glob` **{String|Array}**: Filepaths or glob patterns.\n* `tasks` **{Array}**: Task(s) to watch.\n\n**Example**\n\n```js\napp.task('watch', function() {\n  app.watch('docs/*.md', ['docs']);\n});\n```\n\n## Plugins\n\n### Discovering plugins\n\nPlugins from any applications built on [base](https://github.com/node-base/base) should work with Assemble and can be used in your `assemblefile.js`:\n\n* [base](https://www.npmjs.com/browse/keyword/baseplugin): find base plugins on npm using the `baseplugin` keyword\n* [assemble](https://www.npmjs.com/browse/keyword/assembleplugin): find assemble plugins on npm using the `assembleplugin` keyword\n* [generate](https://www.npmjs.com/browse/keyword/generateplugin): find generate plugins on npm using the `generateplugin` keyword\n* [templates](https://www.npmjs.com/browse/keyword/templatesplugin): find templates plugins on npm using the `templatesplugin` keyword\n* [update](https://www.npmjs.com/browse/keyword/updateplugin): find update plugins on npm using the `updateplugin` keyword\n* [verb](https://www.npmjs.com/browse/keyword/verbplugin): find verb plugins on npm using the `verbplugin` keyword\n\n### Authoring plugins\n\nVisit the [plugin documentation](docs/plugins.md) guide to learn how to use, author and publish plugins.\n\n## Learning\n\n### Help\n\n**Get in touch!**\n\nHave questions, suggestions, or want to discuss assemble? Join the conversation on [gitter](http://gitter.im/assemble/assemble) or give us a shout on [twitter](https://twitter.com/assemblejs). The assemble team and community are always happy to help!\n\n### More information\n\n* ~~[Documentation](docs)~~ (Temporarily, while we work on the new website, docs can be found in [support/docs/src](support/docs/src))\n* [API documentation](support/docs/src/content/api.md)\n* [Generators maintained by the core team](https://github.com/generate)\n\n### FAQ\n\n**Website is outdated and being refactored!**\n\nAssemble's website, assemble.io, only has information related to [gulp-assemble](http://assemble.io). We're working hard to update the site with information about the latest release.\n\nIn the meantime, you might find the [WIP docs](docs/src/content) useful. The [unit tests](test/) are also great examples!\n\n**Is the assemble website up-to-date?**\n\nNo, as mentioned above, it's completely out-of-date. If you're using [grunt-assemble](https://github.com/assemble/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.\n\nWe're actively (daily) working on a refactor and it's a very high priority.\n\n**What's the difference between [assemble-core](https://github.com/assemble/assemble-core) and assemble?**\n\nAssemble 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](https://github.com/assemble/assemble-core) is a great starting point.\n\nIf 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](https://github.com/jonschlinkert/templates) instead of assemble-core.\n\n**I use gulp, why is it recommended to use assemble directly, instead of running assemble with gulp?**\n\nYou 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.\n\nFor 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](https://github.com/assemble/assemble-handle) plugin with gulp to ensure that the handlers are still called as needed.\n\nThis 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.\n\n**What is the relationship between gulp and assemble?**\n\nPlease read our [gulp FAQ](docs/src/subjects/gulp-faq.md) for more information.\n\n## About\n\n### Community\n\nGet updates on Assemble's development and chat with the project maintainers and community members.\n\n* Follow [@assemblejs on Twitter](https://twitter.com/assemblejs).\n\n* If you like Assemble and want to tweet about it, please feel free to mention `@assemblejs` or use the `#assemble` hashtag\n\n* Read and subscribe to [The Official Assemble Blog](https://github.com/assemble/assemble/blog).\n* Join [the official Slack room](https://assemble.github.io/slack).\n* Join the [conversation on Gitter](https://gitter.im/assemble/assemble?utm_source=share-link\u0026utm_medium=link\u0026utm_campaign=share-link)\n\n* Tell us about [your assemble project](https://github.com/assemble/assemble/issues/300)\n* Show your love by starring Assemble!\n* Get implementation help on [StackOverflow](http://stackoverflow.com/questions/tagged/assemble) (please use the [assemble](https://stackoverflow.com/questions/tagged/assemble)`assemble` tag in questions)\n* **Gitter** Discuss Assemble with us on [Gitter](https://gitter.im/assemble/assemble)\n\n* 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](https://www.npmjs.com/browse/keyword/assemble) or similar delivery mechanisms.\n\n**Contributing**\n\nPlease read our [contributing guide](.github/contributing.md) if you'd like to learn more about contributing to this project.\n\n### Related projects\n\nYou might also be interested in these projects from [@doowb](https://github.com/doowb) and [@jonschlinkert](https://github.com/jonschlinkert):\n\n* [boilerplate](https://www.npmjs.com/package/boilerplate): Tools and conventions for authoring and using declarative configurations for project \"boilerplates\" that can be… [more](https://github.com/jonschlinkert/boilerplate) | [homepage](https://github.com/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.\")\n* [generate](https://www.npmjs.com/package/generate): Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… [more](https://github.com/generate/generate) | [homepage](https://github.com/generate/generate \"Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the robustness and configurability of Yeoman, the expressiveness and simplicity of Slush, and more powerful flow control and composability than either.\")\n* [scaffold](https://www.npmjs.com/package/scaffold): Conventions and API for creating declarative configuration objects for project scaffolds - similar in format… [more](https://github.com/jonschlinkert/scaffold) | [homepage](https://github.com/jonschlinkert/scaffold \"Conventions and API for creating declarative configuration objects for project scaffolds - similar in format to a grunt task, but more portable, generic and can be used by any build system or generator - even gulp.\")\n* [update](https://www.npmjs.com/package/update): Be scalable! Update is a new, open source developer framework and CLI for automating updates… [more](https://github.com/update/update) | [homepage](https://github.com/update/update \"Be scalable! Update is a new, open source developer framework and CLI for automating updates of any kind in code projects.\")\n* [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb \"Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.\")\n\n### Similar projects\n\nIf 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):\n\n**Static site generators**\n\n* [docpad](https://github.com/docpad)\n* [metalsmith](https://github.com/metalsmith)\n* [punch](https://github.com/laktek/punch)\n* [wintersmith](https://github.com/jnordberg/wintersmith)\n\n**Blog frameworks**\n\n* [hexojs](https://github.com/hexojs)\n* [ghost](https://github.com/TryGhost/Ghost)\n\n### Release history\n\nChangelog entries are classified using the following labels _(from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog)_):\n\n* `added`: for new features\n* `changed`: for changes in existing functionality\n* `deprecated`: for once-stable features removed in upcoming releases\n* `removed`: for deprecated features removed in this release\n* `fixed`: for any bug fixes\n\nCustom labels used in this changelog:\n\n* `dependencies`: bumps dependencies\n* `housekeeping`: code re-organization, minor edits, or other changes that don't fit in one of the other categories.\n\n#### [0.24.0](https://github.com/assemble/assemble/compare/0.23.0...0.24.0) - 2017-05-19\n\n**added**\n\n* By popular request, assemble now automatically expands config templates in yaml front-matter, via [expand-front-matter](https://github.com/jonschlinkert/expand-front-matter)! This is a feature that we had in grunt-assemble, and users let us know that they wanted it back.\n\n**fixed**\n\n* Updated dependencies to use [is-binary-buffer](https://github.com/jonschlinkert/is-binary-buffer), which fixes a bug where `isbinaryfile` was trying to read from a file that didn't exist.\n\n#### [0.23.0](https://github.com/assemble/assemble/compare/0.21.0...0.23.0) - 2017-02-11\n\n**dependencies**\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to get an update to [assemble-streams](https://github.com/assemble/assemble-streams) that ensures that `view` is decorated with `.toStream()` when created by `app` (versus a collection).\n\n#### [0.21.0](https://github.com/assemble/assemble/compare/0.20.0...0.21.0) - 2017-02-03\n\n**dependencies**\n\n* Bumps [assemble-loader](https://github.com/assemble/assemble-loader) to v1.0.0 to take advantage of optimizations, improvements and bug fixes related to loading views\n\n**fixed**\n\n* Regression in 0.20.0 that was causing `view.stat` to be null in some cases after `view.path` changed\n* `view.base` was not always correct on views that were not created from the file system\n\n#### [0.20.0](https://github.com/assemble/assemble/compare/0.19.0...0.20.0) - 2017-02-02\n\n**dependencies**\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.29.0 to take advantage of improvements to `dest` handling\n\n#### [0.19.0](https://github.com/assemble/assemble/compare/0.18.0...0.19.0) - 2017-02-01\n\n**dependencies**\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.28.0 to take advantage of new methods available on `list`s\n\n##### [0.18.0](https://github.com/assemble/assemble/compare/0.17.0...0.18.0)\n\n**Dependencies**\n\n* bumps [assemble-core](https://github.com/assemble/assemble-core) to 0.27.0\n\n##### [0.17.0](https://github.com/assemble/assemble/compare/0.16.1...0.17.0)\n\n**Dependencies**\n\n* bumps [assemble-core](https://github.com/assemble/assemble-core) to 0.26.0\n\n##### [0.16.1](https://github.com/assemble/assemble/compare/0.16.0...0.16.1)\n\n* bump dependencies. In particular, there was a bug in [parser-front-matter](https://github.com/jonschlinkert/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.\n\n##### [0.16.0](https://github.com/assemble/assemble/compare/0.15.0...0.16.0)\n\n* **Added**: `.log()` method, which also exposes additional methods, like `.log.info()`, `.log.success()`, etc.\n* docs were moved to `support/docs`, so that markdown docs can be built to the `docs` directory\n* docs were updated, new docs added\n* Moves some private prototype methods to static methods, to allow them to be used without creating an instance\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.25.0\n\n##### [0.15.0](https://github.com/assemble/assemble/compare/0.14.0...0.15.0)\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.24.0 to get the latest versions of [templates](https://github.com/jonschlinkert/templates) and [base-data](https://github.com/node-base/base-data) which removes the `renameKey` option from the `.data` method. Use the `namespace` option instead.\n\n##### [0.14.0](https://github.com/assemble/assemble/compare/0.13.0...0.14.0)\n\nBumps [assemble-core](https://github.com/assemble/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](../../issues) if regressions occur.\n\n* fixes `List` bug that was caused collection helpers to explode\n* Improvements to lookup functions: `app.getView()` and `app.find()`\n* Bumps [base](https://github.com/node-base/base) to take advantages of code optimizations.\n\n##### [0.13.0](https://github.com/assemble/assemble/compare/0.12.0...0.13.0)\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.21.0. Support for the `queue` property was removed on collections. See [assemble-core](https://github.com/assemble/assemble-core) for additional details.\n* 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.\n* 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\n* Externalizes common [templates](https://github.com/jonschlinkert/templates) tests to base-test-runner, so that assemble plugins and other [base](https://github.com/node-base/base) applications can use the tests\n* Includes a fix from [assemble-loader](https://github.com/assemble/assemble-loader), where a bug caused `renameKey` to not always be used when defined on collection loader options.\n* Includes fixes from templates for resolving layouts\n\n##### [0.12.0](https://github.com/assemble/assemble/compare/0.11.0...0.12.0)\n\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.18.0, which includes a bump in [templates](https://github.com/jonschlinkert/templates). See the changelog on the templates library for more details.\n\n##### [0.11.0](https://github.com/assemble/assemble/compare/0.10.0...0.11.0)\n\n* `debug` methods and related code have been removed\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.17.0\n\n##### [0.10.0](https://github.com/assemble/assemble/compare/0.9.0...0.10.0)\n\n* Adds support for using es6 generators with tasks\n* Bumps [assemble-core](https://github.com/assemble/assemble-core) to v0.15.0\n\n##### [0.9.0](https://github.com/assemble/assemble/compare/0.8.0...0.9.0)\n\n* 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`\n\n##### [0.8.0](https://github.com/assemble/assemble/compare/0.7.0...0.8.0)\n\n* Updates [composer](https://github.com/doowb/composer) to v0.11.0, which removes the `.watch` method in favor of using the [base-watch](https://github.com/node-base/base-watch) plugin.\n* Changes in [templates](https://github.com/jonschlinkert/templates). Please see v0.11.0 in [templates history](https://github.com/jonschlinkert/templates#history) for more details.\n\n##### [0.7.0](https://github.com/assemble/assemble/compare/0.6.0...0.7.0)\n\n* Stability improvements and optimizations of the API introduced in v0.6.0.\n\n##### [0.6.0]\n\n* 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](https://github.com/assemble/grunt-assemble). Please see that repo for additional details.\n\n_(Changelog generated by [helper-changelog](https://github.com/helpers/helper-changelog))_\n\n### Contributing\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).\n\nPlease read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.\n\nIf Assemble doesn't do what you need, [please let us know](https://github.com/undefined/issues/new)\n\n### Contributors\n\n| **Commits** | **Contributor** |  \n| --- | --- |  \n| 1497 | [jonschlinkert](https://github.com/jonschlinkert) |  \n| 842  | [doowb](https://github.com/doowb) |  \n| 11   | [AndersDJohnson](https://github.com/AndersDJohnson) |  \n| 7    | [Arkkimaagi](https://github.com/Arkkimaagi) |  \n| 7    | [stefanwalther](https://github.com/stefanwalther) |  \n| 4    | [avr](https://github.com/avr) |  \n| 4    | [bendrucker](https://github.com/bendrucker) |  \n| 2    | [thegreatsunra](https://github.com/thegreatsunra) |  \n| 2    | [rauberdaniel](https://github.com/rauberdaniel) |  \n| 2    | [onokumus](https://github.com/onokumus) |  \n| 2    | [RobLoach](https://github.com/RobLoach) |  \n| 2    | [StevenBlack](https://github.com/StevenBlack) |  \n| 2    | [xzyfer](https://github.com/xzyfer) |  \n| 2    | [ain](https://github.com/ain) |  \n| 1    | [asans](https://github.com/asans) |  \n| 1    | [bauerca](https://github.com/bauerca) |  \n| 1    | [caseyg1204](https://github.com/caseyg1204) |  \n| 1    | [hyzhak](https://github.com/hyzhak) |  \n| 1    | [mootari](https://github.com/mootari) |  \n| 1    | [criticalmash](https://github.com/criticalmash) |  \n| 1    | [joonasy](https://github.com/joonasy) |  \n| 1    | [jordanthomas](https://github.com/jordanthomas) |  \n| 1    | [frayer](https://github.com/frayer) |  \n| 1    | [efender](https://github.com/efender) |  \n| 1    | [pburtchaell](https://github.com/pburtchaell) |  \n| 1    | [scmorrison](https://github.com/scmorrison) |  \n| 1    | [oncletom](https://github.com/oncletom) |  \n| 1    | [tylerhowarth](https://github.com/tylerhowarth) |  \n| 1    | [klokie](https://github.com/klokie) |  \n\n### Authors\n\n**Jon Schlinkert**\n\n* [github/jonschlinkert](https://github.com/jonschlinkert)\n* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)\n\n**Brian Woodward**\n\n* [github/doowb](https://github.com/doowb)\n* [twitter/doowb](http://twitter.com/doowb)\n\n### License\n\nCopyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).\nMIT\n\n***\n\n_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on December 27, 2017._","funding_links":[],"categories":["CSS","static-site-generator","documentation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassemble%2Fassemble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fassemble%2Fassemble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassemble%2Fassemble/lists"}