Assemble makes it dead simple to build modular sites and components from reusable templates and data.
Get the rocks out of your socks. Assemble helps you quickly launch static web projects by emphasizing a strong separation of concerns between structure, style, content and configuration.
This project just launched so expect frequent changes. And if you find this project interesting please consider starring it to receive updates.
Assemble has many more features than we've been able to document thus far. So while we work to improve the docs, please let us know if you have any questions or have any trouble getting Assemble to work. And feel free to create an Issue, we're here to help.
Table of Contents
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 with this line of JavaScript:
grunt.loadNpmTasks('assemble');
When completed, you'll be able to run the various grunt commands provided:
grunt assembleRuns the assemble task to rebuild the project.
grunt testRuns jshint on JavaScripts and mocha unit tests on your templates.
grunt watchRequires grunt-contrib-watch, npm i grunt-contrib-watch. This is a convenience task for watching files and automatically re-building them whenever you save. Requires the grunt-contrib-watch Grunt plugin.
Should you encounter problems with installing dependencies or running the grunt commands, be sure to first uninstall any previous versions (global and local) you may have installed, and then rerun npm install.
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.
Path to "assets" (or "public") folder.
Type: String (optional)
Default: undefined
Used with the {{assets}} template to resolve the relative path to the destination assets folder, from the dest file.
Example:
assemble: {
options: {
assets: 'dist/assets'
},
...
}
Example usage:
<link href="{{assets}}/css/styles.css" rel="stylesheet">
Resulting in:
<link href="dist/assets/css/styles.css" rel="stylesheet">
The data to populate templates.
Type: Object (optional)
Parameters: String|Array
Default: src/data
Gets the data from 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:
page.json
{
"production": false
}
<link href="assets/bootstrap.css" rel="stylesheet">
Note that Handlebars.js is the only supported template engine at this time. If you would like to see another engine added to Assemble, please make a feature request (or pull request).
Example:
assemble: {
options: {
data: ['src/data/*.{json,yml,yaml}', 'config/global.json', 'styles/bootstrap.json']
},
...
}
Data: widget.json (or widget.yml)
{
"name": "Square Widget",
"modifier": "widget-square"
}
Template: widget.hbs
<div class="widget {{ widget.modifier }}">{{ widget.name }}</div>
Compiled result after running grunt assemble:
<div class="widget widget-square">Square Widget</div>
Also see: YAML front matter todo...
Type: String (optional)
Default: undefined
Path to the layout to be used.
assemble: {
options: {
layout: 'src/layouts/default.hbs'
},
files: {
'docs': ['src/files/*.hbs']
}
}
Type: Object (optional)
Parameters: Object|Array
Default: undefined
Accepts minimatch patterns to define the Handlebars partials files, or paths to the directories of files to be used.
assemble: {
options: {
partials: ['src/partials/*.hbs', 'src/snippets/*.hbs']
},
files: {
'docs': ['src/files/*.hbs']
}
}
Type: String (optional)
Default: handlebars
The engine to use for processing client-side templates. Assemble ships Handlebars as the default template engine, if you are interested in using a different engine visit the documentation to see an up-to-date list of template engines.
Pull requests are welcome for additional template engines. Since we're still working to update the docs, you many also contact @doowb for more information or create an [Issue][assemble-issues].
Type: Object|Array (optional)
Default: helper-lib
Path defined to a directory of custom helpers to use with the specified template engine. Assemble currently includes more than 75 built-in Handlebars helpers, since Handlebars is the default engine for Assemble.
assemble: {
options: {
helpers: 'your/custom/helpers'
},
...
}
Type: String
Default: .html
Specify the file extension for destination files. Example:
assemble: {
// Build sitemap from JSON and templates
sitemap: {
options: {
ext: '.xml'
},
files: {
'.': ['path/to/sitemap.tmpl']
}
},
// Build README from YAML and templates
readme: {
options: {
ext: '.md'
},
files: {
'.': ['path/to/readme.tmpl']
}
}
}
Type: Boolean
Default: false
Remove anything after (and including) the first "." in the destination path, then append this value.
Assemble makes the following options available from js-yaml. See js-yaml for more information.
Type: String
Default: null
String to be used as a file path in error/warning messages.
Type: Boolean
Default: false
Makes the loader to throw errors instead of warnings.
Type: String
Default: DEFAULT_SCHEMA
Specifies a schema to use.
A common use case for custom options is to add contexts for development and production environments:
assemble {
myProject: {
options: {
development: true,
production: false
},
files: {
'dest': ['src/templates*.hbs']
}
}
}
In your templates just wrap sections with these contexts to include or exclude content based on current working environment.
{{#development}}
<script src="script.js"></script>
{{/development}}
{{#production}}
<script src="script.min.js"></script>
{{/production}}
Wouldn't it be awesome if you could just use markdown however you wanted, wherever you needed it?
Assemble gives you the flexibility to:
Read more about markdown features and options in the markdown documentation.
Use the markdown expression, {{md}}, to enable importing of external markdown content.
Example #1: using full path
{{md ../path/to/content.md}}
Example #2: using variables Or use a variable instead of setting the path directly inside the template. For example you can add the content variable to a YAML header:
---
page:
title: Home
content: ../path/to/content.md
---
then use it like this:
{{md content}}
The {{#markdown}}{{/markdown}} block expression allows markdown to be written "inline" with any HTML and handlebars content.
Example:
{{#markdown}}
# Inline Markdown is awesome
> this is markdown content
* useful for simple content
* great for blog posts
* easier on the eyes than angle brackets
* even links look prettier
### Pretty links
[Visit Assemble](https://github.com/assemble/assemble)
### Even Prettier links
Embed handlebars templates to make them even prettier.
{{#page.links}}
[{{text}}]({{href}})
{{/page.links}}
{{/markdown}}
Task targets, files and options may be specified according to the grunt Configuring tasks guide.
assemble: {
templates: {
files: {
'index.html': ['index.hbs']
}
}
}
You can specify multiple destination: [source] items in files.
assemble: {
gh_pages: {
files: {
'docs': ['getting-started.hbs'],
'.': ['index.hbs']
}
}
}
Grunt supports filename expansion (also know as globbing) via the built-in [node-glob][node-glob] and [minimatch][minimatch] libraries. So Templates may be used in filepaths or glob patterns.
assemble: {
project: {
files: {
'.': ['templates/*.hbs']
}
}
}
Browse the examples folder to get a better idea of what Assemble can do. To build the examples run grunt examples.
This example shows how to use JSON and handlebars templates to manipulate Bootstrap's grid system. We only have to define the grid one time using templates, then we can updated the grid columns, rows, and even content from a JSON or YAML file.
Screenshot The finished result of the example project looks like this:
This is what our handlebars grid looks like. No really, this is the code for the entire grid!:
{{#grid.container}}
<div class="container">
{{#rows}}
<div class="row">
{{#columns}}
<div class="span{{width}}"> {{md content}} </div>
{{/columns}}
</div>
{{/rows}}
</div>
{{/grid.container}}
And then we use an external data file, either grid.yml or grid.json, to configure the grid and provide the content.
YAML version
This is the data for our grid, written in YAML (grid.yml):
container:
rows:
- columns:
- width: 4
heading: Overview
content: <%= content %>/overview.md
- width: 4
heading: Getting Started
content: <%= content %>/getting-started.md
- width: 4
heading: Basics
content: <%= content %>/basics.md
- columns:
- width: 6
heading: Templates
content: <%= content %>/templates.md
- width: 6
heading: Advanced
content: <%= content %>/advanced.md
JSON version
And the same configuration writtin in JSON (grid.json) instead:
{
"container": {
"rows": [
{
"columns": [
{
"width": 4,
"heading": "Overview",
"content": "<%= content %>/overview.md"
},
{
"width": 4,
"heading": "Getting Started",
"content": "<%= content %>/getting-started.md"
},
{
"width": 4,
"heading": "Basics",
"content": "<%= content %>/basics.md"
}
]
},
{
"columns": [
{
"width": 6,
"heading": "Templates",
"content": "<%= content %>/templates.md"
},
{
"width": 6,
"heading": "Advanced",
"content": "<%= content %>/advanced.md"
}
]
}
]
}
}
If you're satisfied with the default src and dest paths in the assemble, simply run grunt assemble to compile the grid to static HTML. Or run grunt watch to continuously watch files and automatically re-build when changes occur.
Want to help make assemble even better? All constructive feedback and contributions are welcome, so please consider contributing! We can always use help creating, tests, documentation or resolving Issues, but if you have other ideas for how you can help, Brian and I would love to hear them!
https://github.com/assemble/assemble/issues
Jon Schlinkert
Brian Woodward
Copyright 2013 Assemble
(Big plans in the works)
Authored by assemble
This file was generated using Grunt and assemble on Tue Apr 16 2013 06:14:33.
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.