Visit http://assemble.io. Assemble is a full-featured documentation, site and component generator built on Grunt.js.
Assemble makes it dead simple to build modular sites and components from reusable templates and data.
We love contributors, pull requests are welcome and followers are appreciated.
Visit the assemble-examples repo to see a list of example projects, such as:
Table of Contents
It amazes me how flexible this whole system is, as we can dance around all the issues quite easily.
— @Arkkimaagi
If you're having trouble getting started, please create an Issue, we're happy to help.
This plugin requires Grunt ~0.4.1. If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install assemble --save-dev
Once the plugin has been installed, it may be enabled inside your [Gruntfile][Getting Started] with this line of JavaScript:
grunt.loadNpmTasks('assemble');
In your project's Gruntfile, add a section named assemble to the data object passed into grunt.initConfig().
grunt.initConfig({
assemble: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
}
}
});
grunt.loadNpmTasks('assemble');
grunt.registerTask('default', [
'jshint',
'assemble'
]);
Task targets, files and options may be specified according to the grunt Configuring tasks guide.
See the Options section on the Wiki 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: Object|Array
Default: src/data
Retrieves data from any specified JSON and/or YAML files to populate the templates when rendered. Data gets passed through the data object to the options on the assemble task, then to the context in your templates.
Also useful for specifying configuration data, such as when to render certain templates. For example:
Also see: YAML front matter
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: Object|Array
Default: undefined
Specifies the Handlebars partials files, or paths to the directories of files to be used.
Type: Object|Array
Default: helper-lib
Path defined to a directory of custom helpers to use with the specified template engine. Assemble currently includes more than 100+ built-in Handlebars helpers, since Handlebars is the default engine for Assemble.
Type: Object|Array
Default: helper-lib
Path defined to a directory of custom helpers to use with the specified template engine. Assemble currently includes more than 100+ built-in Handlebars helpers, since Handlebars is the default engine for Assemble.
Type: String
Default: .html
Specify the file extension for destination files. Example:
More info about ext.
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][files-object] for more information on files formats.
You can add any custom variables directly to the options block:
assemble {
myProject: {
options: {
custom_option1: 'value',
custom_option2: 'value'
},
files: {
'dest': ['src/templates*.hbs']
}
}
}
This offers a great deal of flexibility, but it's also something that should be done sparingly because your tasks and targets can get out of hand pretty quickly.
Here are a couple of common use cases for custom options variables:
Add custom variables for development stages, such as dev and prod:
assemble {
myProject: {
options: {
dev: true,
prod: false
},
files: {
'dest': ['src/templates*.hbs']
}
}
}
Then we can wrap sections in our templates with these contexts to include or exclude content based on truthy or falsy evalution of the dev and prod variables.
{{#dev}}
<script src="script.js"></script>
{{/dev}}
{{#prod}}
<script src="script.min.js"></script>
{{/prod}}
Get or set metadata to/from package.json:
pkg: grunt.file.readJSON('package.json'),
assemble {
myProject: {
options: {
version: '<%= pkg.version %>'
},
files: {
'dest': ['src/templates*.hbs']
}
}
}
Used in our templates like this: {{version}}
NOTE: It's worth noting that you can accomplish the same end goal by using the options.data object instead of creating a custom "options variable". See the options.data page in the wiki for more detail.
Visit the assemble-examples repo to see a list of example projects.
Simple example of using data files in both .json and .yml format to build Handlebars templates.
assemble: {
docs: {
options: {
data: 'src/data/**/*.{json,yml}'
},
files: {
'dist/': ['src/templates/**/*.hbs']
}
}
}
The example shows how you can use Assemble to generate a markdown formatted readme from Handlebars templates.
assemble: {
readme: {
options: {
flatten: true,
partials: 'src/content/*.hbs',
data: 'package.json',
ext: ''
},
src: 'src/templates/README.md.hbs',
dest: './'
}
}
Visit the assemble-examples-readme repo to see a working example.
.xml sitemapYou can generate a sitemap from a static data source, such as sitemap.json, or use Assemble's built-in pages and page variables to automatically generate a sitemap from all pages in a target.
assemble: {
options: {
flatten: true,
data: 'src/sitemap.json',
ext: '.xml'
},
component: {
files: {
'Sitemap.xml': ['src/sitemap.hbs']
}
}
}
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Please lint and test your code using Grunt.
Jon Schlinkert
Brian Woodward
Copyright 2013 Assemble
This file was generated using Grunt and assemble on Sun Jun 23 2013 10:04:02.
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 3,877 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
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.