Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt, Less.js / lesscss.org, Topcoat, Web Experience Toolkit, and hundreds of other projects to build sites, themes, components, documentation, blogs and gh
npm install grunt-assemble
> Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt, Less.js / lesscss.org, Topcoat, Web Experience Toolkit, and hundreds of other projects to build sites, themes, components, documentation, blogs and gh-pages.
> Versions of grunt-assemble below 0.2.0 have been deprecated and can be found on the 0.1.15-deprecated branch.
Versions of grunt-assemble at and above 0.2.0 contain the code from the original assemble up to version 0.4.42.
> See the migration section for instructions on what to do when upgrading to a new version.
1. Most popular site generator for Grunt.js and Yeoman. Assemble is used to build hundreds of web projects, ranging in size from a single page to 14,000 pages (that we're aware of!). Let us know if you use Assemble.
1. Allows you to carve your HTML up into reusable fragments: partials, includes, sections, snippets... Whatever you prefer to call them, Assemble does that.
1. Optionally use layouts to wrap your pages with commonly used elements and content.
1. "Pages" can either be defined as HTML/templates, JSON or YAML, or directly inside the Gruntfile.
1. It's awesome. Lol just kidding. But seriously, Assemble... is... awesome! and it's fun to use.
...and of course, we use Assemble to build the project's own documentation http://assemble.io:
For more: hear Jon Schlinkert and Brian Woodward discuss Assemble on Episode 98 of the Javascript Jabber Podcast.
~0.4.1_If you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide._
From the same directory as your project's [Gruntfile][Getting Started] and [package.json][], install Assemble with the following command:
``bash`
npm install grunt-assemble --save-dev
Once that's done, add this line to your project's Gruntfile:
`js`
grunt.loadNpmTasks('grunt-assemble');
command._Task targets, files and options may be specified according to the grunt Configuring tasks guide.
In your project's Gruntfile, add a section named
assemble to the data object passed into grunt.initConfig().`js
assemble: {
options: {
assets: 'assets',
plugins: ['permalinks'],
partials: ['includes/*/.hbs'],
layout: ['layouts/default.hbs'],
data: ['data/*.{json,yml}']
},
site: {
src: ['docs/*.hbs'],
dest: './'
}
},
`[grunt]: http://gruntjs.com/
[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
[package.json]: https://npmjs.org/doc/json.html
$3
See the documentation for Options for more information.$3
Type:
Default: Used with the
variable to resolve the relative path from the _dest file_ to the _assets_ folder.$3
Type: String|Array|Object
Default: Specify the data to supply to your templates. Data may be formatted in
, YAML, YAML front matter, or passed directly as an object. Wildcard patterns may also be used.The filenames of the selected files must not collide with the configuration options key names for the assemble build task. For example, the files must not be called
assets.yml,collections.json,….$3
Type: String
Default: The directory to use as the "cwd" for layouts. When this option is defined, layouts may be defined using only the name of the layout.
$3
Type:
Default: A glob pattern to be used to find layouts. When this option is defined, the
option is ignored and layouts specified in templates will be searched for using the specified glob pattern(s).$3
Type: String
Default: If set, this defines the layout file to use for the [task or target][tasks-and-targets]. However, when specifying a layout, unlike Jekyll, _Assemble requires a file extension_ since you are not limited to using a single file type.
$3
Type:
Default: Specify the extension to use for layouts, enabling layouts in YAML front matter to be defined without an extension:
yaml
---
layout: default
---
`[tasks-and-targets]: http://gruntjs.com/configuring-tasks#task-configuration-and-targets
$3
Type:
Default: Specifies the Handlebars partials files, or paths to the directories of files to be used.
$3
Type:
Default: Name of the npm module to use and/or the path(s) to any custom plugins to use. Wildcard patterns may also be used.
See the docs for plugins.
$3
Type:
Default: handlebars-helpersName of the npm module to use and/or the path(s) to any custom helpers to use with the current template engine. Wildcard patterns may also be used.
By default, Assemble includes handlebars-helpers) as a dependency, so any helpers from that library are already available to be used in your templates.
See the docs for helpers.
$3
Type:
Default: Specify the file extension for destination files. Example:
$3
Type:
Default: Marked.js defaultsSpecify the Marked.js options for the
and {{md ""}} helpers to use when converting content.$3
Type: String
Default: Specify the engine to use for compiling templates if you are not using Handlebars.
Also see assemble-swig for compiling Swig Templates.
$3
Type:
Default: Remove anything after (and including) the first
in the destination path, then append this value. In other words, when files are generated from different source folders this "flattens" them into the same destination directory. See building the files object dynamically for more information on files formats.Visit Assemble's documentation for more information about options.
$3
Simple example of using data files in both .json and .yml format to build Handlebars templates.`javascript
assemble: {
options: {
data: 'src/data/*/.{json,yml}'
},
docs: {
files: {
'dist/': ['src/templates/*/.hbs']
}
}
}
`#### Using multiple targets
js
assemble: {
options: {
assets: 'assets',
layoutdir: 'docs/layouts'
partials: ['docs/includes/*/.hbs'],
data: ['docs/data/*/.{json,yml}']
},
site: {
options: {
layout: 'default.hbs'
},
src: ['templates/site/*.hbs'],
dest: './'
},
blog: {
options: {
layout: 'blog-layout.hbs'
},
src: ['templates/blog/*.hbs'],
dest: 'articles/'
},
docs: {
options: {
layout: 'docs-layout.hbs'
},
src: ['templates/docs/*.hbs'],
dest: 'docs/'
}
},
`Visit Assemble's documentation for many more examples and pointers on getting started.
$3
#### Breaking changes between versions
and 0.6.0Version 6 is using [assemble-handlebars][] version
which updates [handlebars-helpers][] to version 0.6.0. Due to this update, there are some breaking changes with how some helpers are loaded and some missing/added helpers.The following list contains the breaking changes that we have noticed that may require updates to existing templates.
helpers loaded from package.json
Any helpers declared in
dependencies or devDependencies and have their name in the keywords property will no longer be loaded automatically. To load the helpers, just include the package name in the helpers option for your grunt-assemble target:`js
assemble: {
options: {
helpers: ['handlebars-helper-eachitems']
}
}
`new path helpers
Helpers have been added that map to methods on the built-in
module. Some of these helpers are also properties that grunt-assemble adds automatically to page properties. To use the page property, use the this keyword before the property name. To use the helper, use it like any other helper.`handlebars
{{this.basename}}
{{basename this.path}}
`missing helper "inspect"
The "inspect" helper has been removed from
. The test fixtures in this project use the "inspect" helper so it has been recreated here.missing helper "unless_eq"
The "unless_eq" helper has been renamed to "unlessEq".
missing helper "md" or "markdown"
There is a bug in
handlebars-helpers@0.6 that causes the md and markdown helpers to not be registered correctly. This has been fixed in newer versions of handlebars-helpers, however those changes have not made it here yet. There is currently a refactor of grunt-assemble that will include the fix, but for now, use the following work-around:Create a file and register the helpers manually:
`js
// helpers/markdown.js
module.exports.register = function (Handlebars) {
'use strict'; Handlebars.registerHelper('markdown', require('helper-markdown')());
Handlebars.registerHelper('md', require('helper-md').sync);
};
`js
// Gruntfile.js
assemble: {
options: {
helpers: ['./helpers/*.js']
}
}
`handlebars 4 changed how context depths are handled
is also using a newer version of handlebars that changed how the context depth is handled. Some of the block helpers that would create a new depth, no longer create the depth. This requires changing some templates that use the {{../}} syntax to reduce the amount of ../ segments used. This can be seen in block helpers that don't modify the context, like {{#if}}{{/if}} and {{#is}}{{/is}}.
[assemble-handlebars]: https://github.com/assemble/assemble-handlebars
[handlebars-helpers]: https://github.com/assemble/handlebars-helpers
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality, and please re-build the documentation with grunt-verb before submitting a pull request.
Assemble plugins
Here are some related projects you might be interested in from the Assemble core team.+ assemble-middleware-anchors: Assemble middleware for creating anchor tags from generated html.
+ assemble-middleware-contextual: Assemble middleware for generating a JSON file containing the context of each page. Basic middleware to help see what's happening in the build.
+ assemble-middleware-decompress: Assemble plugin for extracting zip, tar and tar.gz archives.
+ assemble-middleware-download: Assemble middleware for downloading files from GitHub.
+ assemble-middleware-drafts: Assemble middleware (v0.5.0) for preventing drafts from being rendered.
+ assemble-middleware-i18n: Assemble middleware for adding i18n support to projects.
+ assemble-middleware-lunr: Assemble middleware for creating a search engine within your static site using lunr.js.
+ assemble-middleware-permalinks: Permalinks middleware for Assemble, the static site generator for Grunt.js and Yeoman. This plugin enables powerful and configurable URI replacement patterns, presets, uses Moment.js for parsing dates, and much more.
+ assemble-middleware-rss: Assemble middleware for creating RSS feeds with Assemble. (NOT published yet!)
+ assemble-middleware-sitemap: Assemble middleware for generating sitemaps.
+ assemble-middleware-toc: Assemble middleware for creating a table of contents in the generated HTML, using Cheerio.js
+ assemble-middleware-wordcount: Assemble middleware for displaying a word-count, and estimated reading time on blog posts or pages.
Visit assemble.io/assemble-middleware for more information about Assemble middleware.
Authors
Jon Schlinkert
+ github/jonschlinkert
+ twitter/jonschlinkert
Brian Woodward
+ github/doowb
+ twitter/doowb
Release History
DATE VERSION CHANGES
* 2014-07-07 v0.4.41 Updating resolve-dep dependency.
* 2014-06-13 v0.4.38 Use gray-matter instead of assemble-yaml.,Updates dependencies. Minor
refactoring and new utils to get rid of a couple of dependencies.,Update
the loaders for plugins and helpers to use resolve-dep. Should be more
reliable now.
* 2013-10-25 v0.4.17 Adds a params object to the call to helper.register allowing grunt and
assemble to be passed in and used from inside helpers.
* 2013-10-24 v0.4.16 Adds support for using wildcards with plugins stages.
* 2013-10-24 v0.4.15 Implements multiple plugin stages.
* 2013-10-21 v0.4.14 Adds support for plugins running once, before and after (thanks
@adjohnson916).,Adds pagination!,Thanks to @xzyfer, options.data can now
also directly accept an object of data.
* 2013-10-12 v0.4.13 Adds originalAssets property to root context to store the pre-calculated
assets path
* 2013-10-05 v0.4.12 Fixes plugins resolving for devDependencies.
* 2013-10-03 v0.4.11 Adds filePair to page object. thanks @adjohnson916!
* 2013-10-02 v0.4.10 Adds plugin support to Assemble using the plugins option. thanks
@adjohnson916!
* 2013-10-02 v0.4.9 Adds layoutext and postprocess` options. *
_This file was generated by grunt-verb on March 17, 2017._