Assemble makes it dead simple to build modular sites and components from reusable templates and data.
Assemble makes it dead simple to build modular sites and components from reusable templates and data.
This project just launched so expect frequent changes. 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: 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:
development stages
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}}
version consistency
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']
}
}
}
Let's start by creating a template, which can be any kind of markdown, text, xml or markup/HTML that we want to use. For this example our template is going to be HTML, and since I'm feeling creative let's call it my-template.hbs.
Now, focusing only on the head of our HTML document, let's add template variables for title and author so that we can later replace them with real data:
<!DOCTYPE html>
<html lang="en">
<head>
<title>{{title}}</title>
<meta name="author" content="{{author}}">
</head>
<body>
</body>
</html>
Handlebars.js is the default template engine in Assemble, so our variables are wrapped in "Handlebars expressions": {{ and }}.
For data we can mix and match any of the following formats:
my-data.jsonmy-data.ymlWhen working with "external" data files, if we name our file the same as our template, and we add the path to the data file to the options.data object in the assemble task, then Assemble will pick it up and use it automatically.
Here is an example of what we might put inside of my-template.json to populate our template with data.
{
"title": "Assemble",
"author": "Brian Woodward"
}
Here is the same in YAML format: my-template.yml
title: Assemble
author: Brian Woodward
And this template:
my-template.hbs
<h1>{{ title }}</h1>
Or, in cases where we only require simple metadata we can use YAML Front-matter to eliminate the need for an external data file:
---
title: Assemble
author: Brian Woodward
---
<h1>{{ title }}</h1>
Outputs:
<h1>Assemble</h1>
<p>Brian Woodward</p>
Furthermore, we can optionally use underscore templates in the YAML front-matter to translate external variables into data inside the content:
---
title: <%= some.title.variable %>
author: <%= some.author.variable %>
---
<h1>{{ title }}</h1>
<p>{{ author }}</p>
init methodDescribes init method to assemble.engine, and exposes engine on assemble.engine.
If you don't wish to use Handlebars as your templates engine, you may add your own engine by providing an init function that takes in options from the assemble task/target. You may also override the init function in the task/target options by providing an initializeEngine function that takes the engine and the options:
assemble: {
options: {
engine: 'consolidate',
initializeEngine: function(engine, options) {
engine.engine.swig.init(options);
}
},
docs: {
files: {
'docs/': ['src/templates/**/*.tmpl']
}
}
}
Assemble will attempt to load an engine and automatically add it's own wrapper methods around it while holding an instance of the engine. This is a way for engine plugin authors to write adapters between other engines and assemble's wrapper. To make these functions on the options useful, we've exposed the underlying engine through the assemble.engine object so developers can use the raw engine.
This is particularly useful when a) a library such as consolidate is used, where the engine is consolidate, and b) the developer wants to use another engine such as handlebars, swig, mustache etc.
init function allows assemble to pass in options to be used in initializing this engine plugin.init function is exposed, and helper-lib is registered inside the init so that options can be passed in.Admittedly, the engine.engine syntax is strange. This is "alpha", so feedback and pull requests are especially welcome if you have ideas for improving this.
Call registerFunctions, to register custom helpers or "filters", by passing in an engine:
registerFunctions(assemble.engine);
Example of how this would be setup in the options of the assemble task or target:
assemble: {
options: {
registerFunctions: function(engine) {
var helperFunctions = {};
helperFunctions['foo'] = function() { return 'bar'; };
engine.registerFunctions(helperFunctions);
}
},
site: {
files: {
'dist/': ['src/templates/**/*.tmpl']
}
}
}
Call registerPartial by passing in an engine.
registerPartial(assemble.engine, 'partialName', content);
Example of how this would be setup in the options of the assemble task or target:
assemble: {
options: {
registerPartial: function(engine, name, content) {
var tmpl = engine.compile(content);
engine.registerPartial(name, tmpl);
}
},
blog: {
files: {
'dist/blog/': ['src/templates/**/*.tmpl']
}
}
}
Methods to the assemble object can be created using:
var assemble = require('assemble').init(this);
this object is from the grunt task, and can be accessed in assemble "steps" through assemble.taskinit method does some initial option configuration and sets the following properties on the assemble object:assemble.task; // refers to the grunt task
assemble.options; // refers to the task.options merged with assemble defaults
assemble.files; // refers to the task.files
There are also methods to setup the assemble steps, and then execute the build:
The step function takes a function which takes 2 parameters function(assemble, next):
assemble is the actual assemble objectnext is a callback function that needs to be called when finished executing this stepSee the following example:
assemble.step(function(assemble, next) {
// do some code here
// you can add properties to assemble which can be accessed in later steps
assemble.myCustomProperty = { foo: 'bar' };
// always call next when finished and pass back the assemble object
next(assemble);
});
step functionThe step function also returns the current assemble object so it's chainable...
var assemble = require('assemble').init(this)
.step(step1)
.step(step2)
.step(step3)
.build(done);
build functionThe build function takes a callback that is called when the build process is complete. The build process calls the steps that were previously setup, passing in the assemble object.
assemble.build(function(err, result) {
if(err) {
console.log(err);
return;
}
console.log('finished building');
});
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 Wed May 22 2013 16:44:26.
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.