grunt-assemble

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.

npm install grunt-assemble
5 downloads in the last day
28 downloads in the last week
91 downloads in the last month

grunt-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.

WARNING!!!

grunt-assemble uses the alpha branch of Assemble (v0.5.0).

This is not ready to be used unless you're willing to deal with daily changes, broken code, and lack of documentation.

Visit the website →

Why use Assemble?

  1. Most popular site generator for Grunt.js and Yeoman. Assemble is used to build 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 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 grunt-assemble --save-dev

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

grunt.loadNpmTasks('grunt-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',
    plugins: ['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.

plugins

Type: String|Array Default: undefined

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

See the docs for plugins.

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.

postprocess

Type: Function Default: undefined

Function to use for post-processing generated HTML.

Examples

"Prettify" HTML

npm install pretty, then add the following config to apply formatting to any generated HTML:

options: {
  postprocess: require('pretty')
}

String transformations

npm install frep and add the following config to find and replace content:

options: {
  postprocess: function(src) {
    return require('frep').replaceStr(src, [
      {
        // Remove leading whitespace
        pattern: /^\s*/,
        replacement: ""
      },
      {
        // replace "Jekyll" with "Assemble" (jk ;-)
        pattern: "Jekyll",
        replacement: "Assemble"
      }
    ]);
  }
}

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

Type: String Default: Handlebars

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

PLEASE NOTE that this option is only necessary if:

a. You are not using Handlebars, or b. You need to "force" Handlebars to recognize a non-default extension. See extensions.yml.

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.

Examples

Gruntfile configuration examples for the "assemble" task

Prettify HTML

Use js-prettify with Assemble's postprocess option to format generated HTML

To get started, in the command line run npm i js-prettify --save-dev to add js-prettify to your project.

Prettify all generated HTML

Use the postprocess option to prettify output HTML for all targets in the task:

assemble: {
  options: {
    postprocess: require('pretty')
  },
  site: {
    files: {
      'site/': ['templates/site/*.hbs']
    }
  }
}

Prettify a single target

If you only want to format the generated HTML for a specific target, just put use the postprocess function in the options for that target:

assemble: {
  options: {
    // task-level options
  },
  site: {
    options: {postprocess: require('pretty')},
    files: {
      'site/': ['templates/site/*.hbs']
    }
  }
}

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 plugins

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

Visit assemble.io/plugins for more information about Assemble plugins.

Authors

Jon Schlinkert

Brian Woodward

Release History

DATE VERSION CHANGES

  • 2013-12-01 v0.5.0-alpha Starting major refactoring.
  • 2013-10-25 v0.4.17 Adds a params object to the call to helper.register allowing grunt and
                            assemble to be passed in and used from inside helpers.                     
    
  • 2013-10-24 v0.4.16 Adds support for using wildcards with plugins stages.
  • 2013-10-24 v0.4.15 Implements multiple plugin stages.
  • 2013-10-21 v0.4.14 Adds support for plugins running once, before and after (thanks
                            @adjohnson916).,Adds pagination!,Thanks to @xzyfer, `options.data` can now 
                            also directly accept an object of data.                                    
    
  • 2013-10-12 v0.4.13 Adds originalAssets property to root context to store the pre-calculated
                            assets path                                                                
    
  • 2013-10-05 v0.4.12 Fixes plugins resolving for devDependencies.
  • 2013-10-03 v0.4.11 Adds filePair to page object. thanks @adjohnson916!
  • 2013-10-02 v0.4.10 Adds plugin support to Assemble using the plugins option. thanks
                            @adjohnson916!                                                             
    
  • 2013-10-02 v0.4.9 Adds layoutext and postprocess options.
  • 2013-09-30 v0.4.8 Assemble now builds 30-50% faster due to some refactoring to async and how
                            context is calculated.                                                     
    
  • 2013-09-20 v0.4.7 Adds grunt-readme to make it easier to keep the readme updated using
                            templates.,Keep options.partials intact so they can be used in helpers.    
    
  • 2013-09-15 v0.4.6 Updating how the assets path is calculated.,Adding resolve-dep and ability
                            to load helpers from node modules using minimatch patterns                 
    
  • 2013-09-03 v0.4.5 Bug fix: allow page content containing $.,Add alias metadata for data on
                            pages configuration object.                                                
    
  • 2013-08-01 v0.4.4 Adds "nested layouts",Adds option for pages in JSON/YAML collections to be
                            defined as either objects or keys in an array.                             
    
  • 2013-08-01 v0.4.3 Adds "options.pages" for passing in an array of pages in JSON or YAML
                            format.                                                                    
    
  • 2013-06-20 v0.4.0 Adds "layoutdir" option for defining the directory to be used for layouts.
                            If layoutdir is defined, then layouts may be defined using only the name of
                            the layout.                                                                
    
  • 2013-06-10 v0.3.81 Adds additional ways to load custom helpers. Now it's possible to use a
                            glob pattern that points to a list of scripts with helpers to load.,Adds   
                            examples and tests on how to use the new custom helper loading methods.    
    
  • 2013-06-01 v0.3.80 Fixing bug with null value in engine
  • 2013-05-07 v0.3.77 Updated README with info about assemble methods
  • 2013-04-28 v0.3.74 Updating the assemble library to use the assemble-utils repo and
                            unnecessary code.                                                          
    
  • 2013-04-21 v0.3.73 Fixing how the relative path helper worked and showing an example in the
                            footer of the layout. This example is hidden, but can be seen by doing view
                            source.                                                                    
    
  • 2013-04-20 v0.3.72 Fixing the layout override issue happening in the page yaml headers.
                            Something was missed during refactoring.                                   
    
  • 2013-04-19 v0.3.9 Adds tags and categories to the root context and ensure that the current
                            page context values don't override the root context values.                
    
  • 2013-04-18 v0.3.8 Updating to use actual assets property from current page.
  • 2013-04-17 v0.3.7 Cleaning up some unused folders and tests
  • 2013-04-16 v0.3.6 Fixed missing assets property.
  • 2013-04-16 v0.3.5 Adds a sections array to the template engine so it can be used in helpers.
  • 2013-04-11 v0.3.4 More tests for helpers and global variables, organized tests. A number of
                            bug fixes.                                                                 
    
  • 2013-04-06 v0.3.3 helper-lib properly externalized and wired up. Global variables for
                            filename, ext and pages                                                    
    
  • 2013-03-22 v0.3.22 Merged global and target level options so data and partial files can be
                            joined                                                                     
    
  • 2013-03-22 v0.3.21 Valid YAML now allowed in options.data object (along with JSON)
  • 2013-03-18 v0.3.14 new relative helper for resolving relative paths

License

Copyright (c) 2014 Assemble, contributors.
Released under the MIT license


This file was generated by grunt-verb on April 22, 2014.

npm loves you