grunt-assemble
Advanced tools
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
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-assemblebelow0.2.0have been deprecated and can be found on the0.1.15-deprecatedbranch. Versions ofgrunt-assembleat and above0.2.0contain the code from the originalassembleup to version0.4.42.
See the migration section for instructions on what to do when upgrading to a new version.
layouts to wrap your pages with commonly used elements and content....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.
Assemble requires Grunt ~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 and package.json, install Assemble with the following command:
npm install grunt-assemble --save-dev
Once that's done, add this line to your project's Gruntfile:
grunt.loadNpmTasks('grunt-assemble');
Run the "assemble" task with the 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().
assemble: {
options: {
assets: 'assets',
plugins: ['permalinks'],
partials: ['includes/**/*.hbs'],
layout: ['layouts/default.hbs'],
data: ['data/*.{json,yml}']
},
site: {
src: ['docs/*.hbs'],
dest: './'
}
},
See the documentation for Options for more information.
Type: String
Default: undefined
Used with the {{assets}} variable to resolve the relative path from the dest file to the assets folder.
Type: String|Array|Object
Default: src/data
Specify the data to supply to your templates. Data may be formatted in JSON, 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,….
Type: String
Default: undefined
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.
Type: String|Array<String>
Default: undefined
A glob pattern to be used to find layouts. When this option is defined, the layoutdir option is ignored and layouts specified in templates will be searched for using the specified glob pattern(s).
Type: String
Default: undefined
If set, this defines the layout file to use for the task or target. However, when specifying a layout, unlike Jekyll, Assemble requires a file extension since you are not limited to using a single file type.
Type: String
Default: undefined
Specify the extension to use for layouts, enabling layouts in YAML front matter to be defined without an extension:
---
layout: default
---
Type: String|Array
Default: undefined
Specifies the Handlebars partials files, or paths to the directories of files to be used.
Type: String|Array
Default: undefined
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.
Type: String|Array
Default: handlebars-helpers
Name 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.
Type: String
Default: .html
Specify the file extension for destination files. Example:
Type: Object
Default: Marked.js defaults
Specify the Marked.js options for the {{#markdown}}{{/markdown}} and {{md ""}} helpers to use when converting content.
Type: String
Default: Handlebars
Specify the engine to use for compiling templates if you are not using Handlebars.
Also see assemble-swig for compiling Swig Templates.
Type: Boolean
Default: false
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.
Simple example of using data files in both .json and .yml format to build Handlebars templates.
assemble: {
options: {
data: 'src/data/**/*.{json,yml}'
},
docs: {
files: {
'dist/': ['src/templates/**/*.hbs']
}
}
}
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.
0.5.0 and 0.6.0Version 6 is using assemble-handlebars version 0.4.0 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:
assemble: {
options: {
helpers: ['handlebars-helper-eachitems']
}
}
new path helpers
Helpers have been added that map to methods on the built-in path 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.
{{this.basename}}
{{basename this.path}}
missing helper "inspect"
The "inspect" helper has been removed from handlebars-helpers. 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:
// helpers/markdown.js
module.exports.register = function (Handlebars) {
'use strict';
Handlebars.registerHelper('markdown', require('helper-markdown')());
Handlebars.registerHelper('md', require('helper-md').sync);
};
// Gruntfile.js
assemble: {
options: {
helpers: ['./helpers/*.js']
}
}
handlebars 4 changed how context depths are handled
assemble-handlebars 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}}.
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.
Here are some related projects you might be interested in from the Assemble core team.
Visit assemble.io/assemble-middleware for more information about Assemble middleware.
Jon Schlinkert
Brian Woodward
DATE VERSION CHANGES
helper.register allowing grunt andoptions.data can now
also directly accept an object of data.originalAssets property to root context to store the pre-calculated
assets pathplugins option. thankslayoutext and postprocess options.Copyright (c) 2017 Jon Schlinkert, Brian Woodward, contributors.
Released under the MIT license
This file was generated by grunt-verb on March 17, 2017.
FAQs
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
The npm package grunt-assemble receives a total of 1,034 weekly downloads. As such, grunt-assemble popularity was classified as popular.
We found that grunt-assemble demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers 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
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.