assemble-collection/README.md

Assemble plugin for creating paginated lists of files using file front matter.

# assemble-collection [![NPM version](https://img.shields.io/npm/v/assemble-collection.svg?style=flat)](https://www.npmjs.com/package/assemble-collection) [![NPM downloads](https://img.shields.io/npm/dm/assemble-collection.svg?style=flat)](https://npmjs.org/package/assemble-collection) [![Build Status](https://img.shields.io/travis/assemble/assemble-collection.svg?style=flat)](https://travis-ci.org/assemble/assemble-collection)

Assemble plugin for creating paginated lists of files using file front matter.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save assemble-collection
```

## Usage

```js
var assemble = require('assemble');
var collection = require('assemble-collection');
var app = assemble();
app.use(collection());
```

## API

### [createIndex](index.js#L37)

Creates a pipeline plugin that will group files into a collection based on the data property specified directly or in the permalink pattern passed on `options`.

List and item index pages will also be created for the entire list of items being grouped and for each individual item.
The item pages will contain all of the files found in that item group.
Custom list and item page templates may be specified by passing a `view` on `options.list` and `options.item`.
The item pages may be paginated by passing an `options.paginate` property with [paginationator](https://github.com/doowb/paginationator) options.

**Params**

* `prop` **{String}**: Proprty to use when creating the index. This should be on the `.data` object. The `prop` will be pulled from the permalink pattern if not passed and `options.pattern` is passed.
* `options` **{Object}**: Options to control how list and item pages are created, how pagination is handled, and how the `file.path` is created on new files.
* `options.pattern` **{String}**: Permalink pattern to use for item pages. When `prop` is not passed, the first `:prop` segment will be used.
* `options.paginate` **{Object}**: Options to pass to [paginationator](https://github.com/doowb/paginationator) to control how item page pagination is handled.
* `options.list` **{Object}**: View instance used to create a new `list` page containing the grouped items and files built from the `prop`.
* `options.item` **{Object}**: View instance used to create new `item` pages for each item in the grouped list. Each item page contains the files containing the specific `prop`.

**Example**

```js
app.task('build', function() {
  return app.toStream('pages')
    .pipe(app.createIndex('tags'))
    .pipe(app.dest('dist'));
});
```

## About

### Related projects

* [group-array](https://www.npmjs.com/package/group-array): Group array of objects into lists. | [homepage](https://github.com/doowb/group-array "Group array of objects into lists.")
* [gulp-collection](https://www.npmjs.com/package/gulp-collection): Gulp plugin to group vinyl files into a collection and create new vinyl files using… [more](https://github.com/doowb/gulp-collection) | [homepage](https://github.com/doowb/gulp-collection "Gulp plugin to group vinyl files into a collection and create new vinyl files using pagination and permalinks.")
* [paginationator](https://www.npmjs.com/package/paginationator): Paginate an array into pages of items. | [homepage](https://github.com/doowb/paginationator "Paginate an array into pages of items.")
* [permalinks](https://www.npmjs.com/package/permalinks): Adds permalink or URL routing/URL rewriting logic to any node.js project. Can be used in… [more](https://github.com/jonschlinkert/permalinks) | [homepage](https://github.com/jonschlinkert/permalinks "Adds permalink or URL routing/URL rewriting logic to any node.js project. Can be used in static site generators, build systems, web applications or anywhere you need to do path transformation or prop-string replacements.")
* [placeholders](https://www.npmjs.com/package/placeholders): Replace placeholder values in a file path. | [homepage](https://github.com/jonschlinkert/placeholders "Replace placeholder values in a file path.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

Please read the [contributing guide](contributing.md) for avice on opening issues, pull requests, and coding standards.

### Building docs

_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

To generate the readme and API documentation with [verb](https://github.com/verbose/verb):

```sh
$ npm install -g verb verb-generate-readme && verb
```

### Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

### Author

**Brian Woodward**

* [github/doowb](https://github.com/doowb)
* [twitter/doowb](http://twitter.com/doowb)

### License

Copyright © 2016, [Brian Woodward](https://github.com/doowb).
Released under the [MIT license](https://github.com/assemble/assemble-collection/blob/master/LICENSE).

***

_This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on August 02, 2016._