Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

assemble

Package Overview
Dependencies
Maintainers
1
Versions
113
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

assemble - npm Package Compare versions

Comparing version 0.3.3 to 0.3.10

.jshintrc

75

package.json
{
"name": "assemble",
"description": "Get the rocks out of your socks. Assemble helps you _quickly launch static web projects_ using HTML and CSS components, scaffolds, client-side templates, mock-data, CSS pre-processors, markdown, YAML, JSON, sensible configuration defaults and a Grunt.js build system to make it work. We us Assemble for gh-pages, documentation, static sites, mocking etc.",
"version": "0.3.3",
"homepage": "https://github.com/sellside/assemble",
"description": "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.",
"version": "0.3.10",
"homepage": "https://github.com/assemble/assemble",
"author": {
"name": "assemble",
"url": "https://github.com/sellside/assemble"
"url": "https://github.com/assemble/assemble"
},

@@ -22,6 +22,6 @@ "contributors": [

"type": "git",
"url": "https://github.com/sellside/assemble.git"
"url": "https://github.com/assemble/assemble.git"
},
"bugs": {
"url": "https://github.com/sellside/assemble/issues"
"url": "https://github.com/assemble/assemble/issues"
},

@@ -31,6 +31,6 @@ "licenses": [

"type": "MIT",
"url": "https://github.com/sellside/assemble/blob/master/LICENSE-MIT"
"url": "https://github.com/assemble/assemble/blob/master/LICENSE-MIT"
}
],
"main": "lib/assemble",
"main": "Gruntfile.js",
"engines": {

@@ -43,6 +43,12 @@ "node": "*"

"dependencies": {
"amdefine": "0.0.4"
"amdefine": "0.0.4",
"handlebars": "~1.0.9",
"lodash": "~1.0.1",
"js-yaml": "~2.0.2",
"marked": "~0.2.8",
"highlight.js": "~7.3.0"
},
"devDependencies": {
"grunt": "~0.4.0rc7",
"assemble-styles": "0.1.0",
"grunt": "~0.4.0",
"testem": "~0.2.68",

@@ -53,31 +59,39 @@ "grunt-mocha-test": "~0.2.0",

"grunt-contrib-watch": "~0.2.0",
"handlebars": "~1.0.9"
"grunt-release": "~0.2.0"
},
"keywords": [
"blog generator",
"blog",
"boilerplate",
"boilerplates",
"assembler",
"bootstrap",
"static HTML",
"gh-pages",
"theme",
"themes",
"build and deployment",
"build system",
"build",
"build system",
"components",
"conventions",
"grunt",
"grunt task",
"gruntplugin",
"grunt plugin",
"build-bootstrapr",
"builder",
"cli",
"compile",
"compiler",
"components",
"conventions",
"deploy",
"example handlebars",
"framework",
"generator",
"gh-pages",
"grunt task",
"grunt",
"gruntplugin",
"handlebars",
"helpers",
"jekyll alternative",
"jekyll static",
"jekyll",
"json data",
"mock data",
"mocking",
"modules",
"mustache",
"node blog",
"node jekyll",
"parse",

@@ -88,4 +102,3 @@ "parser",

"pre-processor",
"pre-processors",
"parser",
"preprocessor",
"render",

@@ -95,4 +108,11 @@ "renderer",

"scaffolds",
"site builder",
"site generator",
"site generators",
"static HTML",
"static site",
"templates",
"templating",
"theme",
"themes",
"tool",

@@ -102,4 +122,5 @@ "toolkit",

"web development",
"yaml data",
"web framework"
]
}
}

@@ -1,74 +0,129 @@

# [Assemble](http://assemble.io)
# [Assemble](http://github.com/assemble/assemble)
> 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.
First and foremost, this project just launched in early 2013 so expect frequent changes. If you find this project interesting, please consider watching or starring it to show your support.
_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._
#### [Please visit the wiki](http://github.com/assemble/assemble/wiki)
**Table of Contents**
- [Assemble](#assemble)
- [Getting Started](#getting-started)
- [Running Assemble](#running-assemble)
- [The "assemble" task](#the-assemble-task)
- [Run Assemble](#run-assemble)
- [About](#about)
- [Options](#options)
- [Task defaults](#task-defaults)
- [Options](#options)
- [assets](#assets)
- [data](#data)
- [engine](#engine)
- [flatten](#flatten)
- [layout](#layout)
- [partials](#partials)
- [Usage Examples](#usage-examples)
- [Bug tracker](#bug-tracker)
- [Contributing](#contributing)
- [Authors](#authors)
- [Related Projects](#related-projects)
- [Copyright and license](#copyright-and-license)
- [engine](#engine)
- [helpers](#helpers)
- [flatten](#flatten)
- [assets](#assets)
- [data](#data)
- [ext](#ext)
- [layout](#layout)
- [partials](#partials)
- [YAML options](#yaml-options)
- [filename](#filename)
- [strict](#strict)
- [schema](#schema)
- [Features](#features)
- [Markdown](#markdown) - NEW documentation
- [Example Projects](#example-projects)
- [Build Bootstrap's Grid with JSON or YAML](#build-bootstraps-grid-with-json-or-yaml)
- [Bug tracker](#bug-tracker)
- [Contributing](#contributing)
- [Authors](#authors)
- [Related Projects](#related-projects)
- [Copyright and license](#copyright-and-license)
**A balance of best practices, convention and configuration**
See some [examples](). todo...
## Getting Started
_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][grunt] before, be sure to check out the [Getting Started][Getting Started] guide._
Assemble helps you _quickly launch web projects_ using HTML and CSS components, scaffolds, client-side templates, mock-data, CSS pre-processors, markdown, YAML, JSON, sensible configuration defaults and a Grunt.js build system to make it work.
From the same directory as your project's [Gruntfile][Getting Started] and [package.json][packageJSON], install this plugin with the following command:
This project was designed to be more about flexibility and speed, and less about opinion and prescription. So we'll give you some examples, and show you _how to speed up your projects_, but we won't force you to do it our way.
``` bash
npm install assemble --save-dev
```
Once that's done, add this line to your project's Gruntfile:
``` js
grunt.loadNpmTasks('assemble');
```
## Getting Started
Assemble uses Grunt.js. If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out Grunt's [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
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.
```shell
npm install assemble --save-dev
```
_This plugin was designed to work with Grunt 0.4.x. If you're still using grunt v0.3.x it's strongly recommended that [you upgrade](http://gruntjs.com/upgrading-from-0.3-to-0.4)._
## The "assemble" task
In your project's Gruntfile, add a section named `assemble` to the data object passed into `grunt.initConfig()`.
``` js
grunt.initConfig({
assemble: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
}
}
});
```
## Running Assemble
#### Run Assemble
_Run assemble with the`grunt assemble` command._
## Options
See [options][assemble-options] for more information.
### Task defaults
Task targets, files and options may be specified according to the grunt [Configuring tasks](http://gruntjs.com/configuring-tasks) guide.
### Task defaults
The `assemble` task will build an included boilerplate by default, so you can get up and running quickly. Here are some pointers to get you started on customizing your project:
* Use Assemble's other boilerplates as examples
* See some [working example's] of projects using Assemble
* Read the [wiki](https://github.com/sellside/assemble/wiki)
* Visit [Toolkit](http://toolkit.io), a more extensive library of UI components and project scaffolds that can be used with Assemble.
#### engine
Type: `String`
Default: `handlebars`
### Options
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.
#### assets
Type: `String` `false`
Pull requests are welcome for additional template engines. Since we're still working to update the docs, you many also contact [@doowb](http://github.com/doowb) for more information or create an [Issue][assemble-issues].
#### helpers
Type: `String`
Default: `undefined`
Path defined to a directory of helpers to use with the specified template engine.
``` js
assemble: {
options: {
helpers: 'assemble-helpers-handlebars'
},
...
}
```
Handlebars, Assemble's default template engine, includes the following built-in helpers: {{#each}}, {{#if}}, and {{#unless}}.
[helper-lib][helper-lib] adds approximately **70 additional helpers**. To include them, follow these instructions:
* Run: `npm install assemble-helpers-handlebars`
* Add `assemble-helpers-handlebars` to the `options.helpers` property
* To learn more visit the [assemble-helpers-handlebars][assemble-helpers-handlebars] repo.
* See the list of [handlebars helpers][helpers-docs] here.
#### flatten
Type: `Boolean`
Default: `false`
TODO...
Remove anything after (and including) the first "." in the destination path, then append this value.
#### data
Type: `String` `false`
#### assets
Type: `String`
Default: `false`

@@ -78,47 +133,124 @@

Used by the `{{assets}}` template to resolve the relative path to the dest assets folder from the dest file.
#### engine
Example:
``` js
assemble: {
options: {
assets: 'dist/assets'
},
...
}
```
Example usage:
``` html
<link href="{{assets}}/css/styles.css" rel="stylesheet">
```
Resulting in:
``` html
<link href="dist/assets/css/styles.css" rel="stylesheet">
```
#### data
Type: `String`
Default: `handlebars`
Default: `src/data`
TODO...
Load data for templates and [configuration][config] from specified `JSON` and/or `YAML` files.
Example:
#### flatten
Type: `boolean`
``` js
assemble: {
options: {
data: ['src/data/*.json', 'config/global.json']
},
...
}
```
Example `widget.json` data file:
``` json
{
"name": "Square Widget",
"modifier": "widget-square"
}
TODO...
```
Example `widget.hbs` template:
``` html
<div class="widget {{ widget.modifier }}">{{ widget.name }}</div>
```
Compiled result after running `grunt assemble`:
``` html
<div class="widget widget-square">Square Widget</div>
```
Also see: [YAML front matter] todo...
#### layout
Type: `String` `false`
Default: `false`
Type: `String`
Default: `undefined`
TODO...
Path to the layout to be used.
``` js
assemble: {
options: {
layout: 'src/layouts/default.hbs'
},
files: {
'docs': ['src/files/*.hbs']
}
}
```
#### partials
Type: `String` `false`
Default: `false`
Type: `String`
Default: `undefined`
TODO...
Accepts [minimatch](https://github.com/isaacs/minimatch) patterns to define the Handlebars partials files, or paths to the directories of files to be used.
``` js
assemble: {
options: {
partials: ['src/partials/*.hbs', 'src/snippets/*.hbs']
},
files: {
'docs': ['src/files/*.hbs']
}
}
```
#### ext
Type: `String`
Default: `.html`
### Usage Examples
Specify the file extension for destination files. Example:
```js
``` js
assemble: {
project: {
// Build sitemap from JSON and templates
sitemap: {
options: {
flatten: true,
assets: "dist/assets",
data: "src/data/*.json",
layout: "src/templates/layouts/layout.mustache",
partials: ["src/templates/partials/*.handlebars"]
ext: '.xml'
},
files: {
"path/to/result.html": "path/to/source.mustache",
"path/to/another.html": ["path/to/sources/*.mustache", "path/to/more/*.mustache"]
'.': ['path/to/sitemap.tmpl']
}
},
// Build README from YAML and templates
readme: {
options: {
ext: '.md'
},
files: {
'.': ['path/to/readme.tmpl']
}
}

@@ -128,15 +260,234 @@ }

## Helpers
See docs for [helpers](https://github.com/sellside/assemble/blob/master/docs/helpers.md).
### YAML options
Assemble makes the following options available from `js-yaml`. See [js-yaml](https://github.com/nodeca/js-yaml) for more information.
#### filename
Type: `String`
Default: `null`
String to be used as a file path in error/warning messages.
#### strict
Type: `Boolean`
Default: `false`
Makes the loader to throw errors instead of warnings.
#### schema
Type: `String`
Default: `DEFAULT_SCHEMA`
Specifies a schema to use.
---
## Features
Many, many more features are already implemented, and we are documenting them as you read this, so **check back frequently for updates**!!!
### Markdown
> Wouldn't it be awesome if you could just _use markdown however you wanted, wherever you needed it_?
Assemble gives you the flexibility to:
* **Write entire documents in markdown**, and later compile them to HTML
* **Keep sections of documents in externalized markdown files**, so they can be imported into other documents
* **Embed or write "inline" markdown** on-the-fly inside HTML documents
_Read more about markdown features and `options` in the [markdown documentation](https://github.com/assemble/assemble/wiki/Markdown)._
#### "Include" or import externalized content
Use the markdown expression, `{{md}}`, to enable importing of external markdown content.
**Example #1: using full path**
``` handlebars
{{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:
``` yaml
---
page:
title: Home
content: ../path/to/content.md
---
```
then use it like this:
``` handlebars
{{md content}}
```
#### Write "inline" markdown
The `{{#markdown}}{{/markdown}}` block expression allows markdown to be written "inline" with any HTML and handlebars content.
Example:
``` handlebars
{{#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}}
```
---
## Example Projects
Browse the [examples][assemble-examples] folder to get a better idea of what Assemble can do. To build the examples run `grunt examples`.
### Build Bootstrap's Grid with JSON or YAML
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:
[![grid](https://github.com/assemble/assemble/blob/master/examples/advanced/dest/assets/grid.png?raw=true)](https://github.com/assemble/assemble/blob/master/examples/advanced/dest/assets/grid.png)
---
This is what our handlebars grid looks like. **_No really, this is the code for the entire grid!_**:
``` html
{{#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`):
``` yaml
---
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:
``` json
{
"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.
## About
> The goal of Assemble is to offer:
* Conventions for building and maintaining static sites and UI pattern libraries, using HTML, CSS/LESS/SASS, client-side templates and structured data
* Patterns for highly reusable layouts, pages, includes/partials, "snippets" and so on
* Strategies for externalizing metadata, data and content into maintainable formats, such as markdown, JSON, YAML, text, HTML and others
* Ability to use simple JSON or YAML to configure and define the structure of entire projects, static sites or component libraries
* Configurable and extensible enough for programmers, but easy for non-programmers to learn and use.
## Bug tracker
Have a bug? Please create an issue here on GitHub that conforms with [necolas's guidelines](https://github.com/necolas/issue-guidelines).
[https://github.com/sellside/assemble/issues](https://github.com/sellside/assemble/issues)
[https://github.com/assemble/assemble/issues][assemble-issues]
## Contributing

@@ -151,10 +502,11 @@

**How you can help**
### Call for help
* We would like to add more template engines to those listed here https://github.com/sellside/assemble/issues/43
* Docs, we can always use help creating more documentation
* Feedback: Use assemble, tell us how to improve, add feature requests.
* Have an idea? Tell us about it. You can contact us via GitHub issues or preferably via email (found on author's profiles)
Want to help make Assemble even awesomer? We can always use help dwindling down the [Issues](https://github.com/assemble/assemble/issues), but here are other ways you can help:
* **Documentation**: we can always use help with docs. Creating new docs, filling in missing information, examples, corrections, grammar. You name it, we need it.
* **Tell us your experience with Assemble**: Use assemble, give us feedback and tell us how to improve, or add feature requests.
* **Have an idea? Tell us about it.** You can contact us via GitHub issues or via email (found on author's profiles)
## Authors

@@ -164,26 +516,35 @@

+ http://github.com/doowb
+ http://twitter.com/doowb
+ http://github.com/doowb
**Jon Schlinkert**
+ http://github.com/jonschlinkert
+ http://twitter.com/jonschlinkert
+ http://github.com/jonschlinkert
## Related Projects
Learn about other open source projects from the folks at [Sellside](http://www.sellside.com).
## Coming Soon!
+ [Upstage](http://github.com/upstage): COMING SOON! We are preparing to launch a library of seriously high quality UI components, each constructed following the same conventions we encourage with Assemble.
+ [Toolkit](http://toolkit.io)
+ [Dry](http://dry.io)
+ [Generate](http://generate.github.com)
+ [Pre](http://pre.io)
## Copyright and license
Copyright 2012 Sellside, Inc.
Copyright 2013 Assemble
[MIT License](LICENSE-MIT)
[MIT License](LICENSE-MIT)
[grunt]: http://gruntjs.com/
[Upgrading]: http://gruntjs.com/upgrading-from-0.3-to-0.4
[Getting Started]: http://gruntjs.com/getting-started
[package.json]: https://npmjs.org/doc/json.html
[assemble-examples]: https://github.com/assemble/assemble-examples/
[assemble-issues]: https://github.com/assemble/assemble/issues?page=1&state=open
[assemble-options]: https://github.com/assemble/assemble/blob/master/docs/options.md
[helpers-docs]: https://github.com/assemble/assemble/blob/master/docs/helpers.md
[helper-lib]: https://github.com/assemble/helper-lib
[templates]: https://github.com/assemble/assemble/wiki/Templates
[config]: https://github.com/assemble/assemble/wiki/Configuration
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc