Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

277 lines (187 sloc) 11.151 kB

assemble NPM version Build Status

Static site generator for Grunt.js and Yeoman. Assemble makes it dead simple to build modular sites, blogs, gh-pages, components and documentation from reusable templates and data.

Visit the website →

grunt-assemble provides a declarative wrapper around Assemble.

Why use Assemble?

  1. Most popular site generator for Grunt.js and Yeoman. Assemble is used on hundreds of web projects ranging in size from a single page to 14,000 pages (that we're aware of!). Let us know if you use Assemble!.
  2. Allows you to carve your HTML up into modular, reusable fragments: partials, includes, sections, snippets... Whatever you prefer to call them, Assemble does that.
  3. Optionally use layouts to wrap your pages with commonly used elements and content.
  4. "Pages" can either be defined as HTML/templates, JSON or YAML, or directly inside the Gruntfile.
  5. It's awesome. Lol just kidding. But seriously, Assemble... is... awesome! and it's fun to use.

...and of course, we use Assemble to build the project's own documentation http://assemble.io:

image

The "assemble" task

Getting Started

assemble requires Grunt ~0.4.1

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, install assemble with the following command:

npm install assemble --save-dev

Once that's done, add this line to your project's Gruntfile:

grunt.loadNpmTasks('assemble');

The "assemble" task

Run the "assemble" task with the grunt assemble command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

In your project's Gruntfile, add a section named assemble to the data object passed into grunt.initConfig().

assemble: {
  options: {
    assets: 'assets',
    middleware: ['permalinks'],
    partials: ['includes/**/*.hbs'],
    layout: ['layouts/default.hbs'],
    data: ['data/*.{json,yml}']
  },
  pages: {
    src: ['docs/*.hbs'],
    dest: './'
  }
},

Options

See the documentation for Options for more information.

assets

Type: String

Default: undefined

Used with the {{assets}} variable to resolve the relative path from the dest file to the assets folder.

data

Type: String|Array|Object

Default: src/data

Specify the data to supply to your templates. Data may be formatted in JSON, YAML, YAML front matter, or passed directly as an object. Wildcard patterns may also be used.

layoutdir

Type: String

Default: undefined

The directory to use as the "cwd" for layouts. When this option is defined, layouts may be defined using only the name of the layout.

layout

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.

layoutext

Type: String

Default: undefined

Specify the extension to use for layouts, enabling layouts in YAML front matter to be defined without an extension:

---
layout: default
---

partials

Type: String|Array

Default: undefined

Specifies the Handlebars partials files, or paths to the directories of files to be used.

middleware

Type: String|Array

Default: undefined

Name of the npm module to use and/or the path(s) to any custom middleware to use. Wildcard patterns may also be used.

See the docs for middleware.

helpers

Type: String|Array

Default: handlebars-helpers

Name of the npm module to use and/or the path(s) to any custom helpers to use with the current template engine. Wildcard patterns may also be used.

By default, Assemble includes handlebars-helpers as a dependency, so any helpers from that library are already available to be used in your templates.

See the docs for helpers.

ext

Type: String

Default: .html

Specify the file extension for destination files. Example:

marked

Type: Object

Default: Marked.js defaults

Specify the Marked.js options for the {{#markdown}}{{/markdown}} and {{md ""}} helpers to use when converting content.

engine

PLEASE NOTE: this option is only necessary if you are not using Handlebars!

Type: String

Default: Handlebars

Specify the engine to use for compiling templates if you are not using Handlebars.

Also see assemble-swig for compiling Swig Templates.

flatten

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.

Visit Assemble's documentation for more information about options.

Usage Examples

Simple example of using data files in both .json and .yml format to build Handlebars templates.

assemble: {
  options: {
    data: 'src/data/**/*.{json,yml}'
  },
  docs: {
    files: {
      'dist/': ['src/templates/**/*.hbs']
    }
  }
}

Using multiple targets

assemble: {
  options: {
    assets: 'assets',
    layoutdir: 'docs/layouts'
    partials: ['docs/includes/**/*.hbs'],
    data: ['docs/data/**/*.{json,yml}']
  },
  site: {
    options: {
      layout: 'default.hbs'
    },
    src: ['templates/site/*.hbs'],
    dest: './'
  },
  blog: {
    options: {
      layout: 'blog-layout.hbs'
    },
    src: ['templates/blog/*.hbs'],
    dest: 'articles/'
  },
  docs: {
    options: {
      layout: 'docs-layout.hbs'
    },
    src: ['templates/docs/*.hbs'],
    dest: 'docs/'
  }
},

Visit Assemble's documentation for many more examples and pointers on getting started.

Contributing

Find a bug? Have a feature request? Please create an Issue.

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality, and run docs in the command line to build the docs with Verb.

Pull requests are also encouraged, and if you find this project useful please consider "starring" it to show your support! Thanks!

Assemble middleware

Here are some related projects you might be interested in from the Assemble core team.

Visit assemble.io/assemble-middleware for more information about Assemble middleware.

Authors

Jon Schlinkert

Brian Woodward

License

Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors.
Released under the MIT license


This file was generated by grunt-verb on May 05, 2014.

Jump to Line
Something went wrong with that request. Please try again.