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.
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 for the near future, and if you find this project interesting please consider starring it to receive updates. If you have any questions or have any trouble getting Assemble to work, please create an Issue, we'd love to help.
Table of Contents
You must use Grunt.js version 0.4.0 with Assemble. Please upgrade if you're still using grunt v0.3.x. 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][packageJSON], install this plugin with the following command:
npm install assemble --save-dev
Once that's done, add this line to your project's Gruntfile:
grunt.loadNpmTasks('assemble');
If Assemble has been installed correctly, running grunt --help at the command line should list Assemble's task or tasks. In addition, Assemble should be listed in package.json as a devDependency, which ensures that it will be installed whenever the npm install command is run.
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.
}
}
});
Run assemble with thegrunt assemble command.
See options for more information.
Task targets, files and options may be specified according to the grunt Configuring tasks guide.
Type: String
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.
Type: String
Default: undefined
Path defined to a directory of helpers to use with the specified template engine.
assemble: {
options: {
helpers: 'assemble-helpers-handlebars'
},
...
}
Handlebars, Assemble's default template engine, includes the following built-in helpers: {{#each}}, {{#if}}, and {{#unless}}.
helper-lib adds approximately 70 additional helpers. To include them, follow these instructions:
npm install assemble-helpers-handlebarsassemble-helpers-handlebars to the options.helpers propertyType: Boolean
Default: false
Remove anything after (and including) the first "." in the destination path, then append this value.
Type: String
Default: false
TODO...
Used by the {{assets}} template to resolve the relative path to the dest 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">
Type: String
Default: src/data
Load data for templates and configuration from specified JSON and/or YAML files.
Example:
assemble: {
options: {
data: ['src/data/*.json', 'config/global.json']
},
...
}
Example widget.json data file:
{
"name": "Square Widget",
"modifier": "widget-square"
}
Example widget.hbs template:
<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
Default: undefined
Path to the layout to be used.
assemble: {
options: {
layout: 'src/layouts/default.hbs'
},
files: {
'docs': ['src/files/*.hbs']
}
}
Type: String
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
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']
}
}
}
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.
Many, many more features are already implemented, and we are documenting them as you read this, so check back frequently for updates!!!
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](http://github.com/assemble/assemble)
### Even Prettier links
Embed handlebars templates to make them even prettier.
{{#page.links}}
[{{text}}]({{href}})
{{/page.links}}
{{/markdown}}
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.
The goal of Assemble is to offer:
Have a bug? Please create an issue here on GitHub that conforms with necolas's guidelines.
https://github.com/assemble/assemble/issues
Please consider contributing! All constructive feedback and contributions are welcome.
Want to help make Assemble even awesomer? We can always use help dwindling down the Issues, but here are other ways you can help:
Brian Woodward
Jon Schlinkert
Copyright 2013 Assemble
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.