## Features

* templates are [vinyl][] files
* rich plugin support, use any [base][] plugin!
* render templates with any [template engine](#engine), including [nunjucks][engine-nunjucks], [handlebars][engine-handlebars], [lodash][engine-lodash] and any consolidate engine!
* [helpers](#helpers): support for sync and async
* [templates collections](#collections) support
* partials and includes
* layouts
* pages
* custom template "types"
* pagination
* [permalinks][assemble-permalinks]
* [middleware](#middleware) can be used to tranform files at any stage in the render cycle
* pagination
* Much more!

## Usage

```js
var templates = require('{%= name %}');
var app = templates();
```

### Example

```js
// register an engine to automatically render `md` files
app.engine('md', require('engine-lodash'));

// create a template collection
app.create('pages');

// add a template to the collection
app.page('post.md', {content: 'This is the <%= title %> page'});

// render it
app.render('post.md', {title: 'Home'}, function(err, view) {
  console.log(view.content);
  //=> 'This is the Home page'
});
```

## API
### Common
This section describes API features that are shared by all Templates classes.

#### .option

Set or get an option value.

**Params**

* `key` **{String|Object}**: Pass a key-value pair or an object to set.
* `val` **{any}**: Any value when a key-value pair is passed. This can also be options if a glob pattern is passed as the first value.
* `returns` **{Object}**: Returns the instance for chaining.

**Example**

```js
app.option('a', 'b');
app.option({c: 'd'});
console.log(app.options);
//=> {a: 'b', c: 'd'}
```

#### .use

Run a plugin on the given instance. Plugins are invoked immediately upon instantiating in the order in which they were defined.

**Example**

The simplest plugin looks something like the following:

```js
app.use(function(inst) {
  // do something to `inst`
});
```

Note that `inst` is the instance of the class you're instantiating. So if you create an instance of `Collection`, inst is the collection instance.

**Params**

* `fn` **{Function}**: Plugin function. If the plugin returns a function it will be passed to the `use` method of each item created on the instance.
* `returns` **{Object}**: Returns the instance for chaining.

**Usage**

```js
collection.use(function(items) {
  // `items` is the instance, as is `this`

  // optionally return a function to be passed to
  // the `.use` method of each item created on the
  // instance
  return function(item) {
    // do stuff to each `item`
  };
});
```

### App
The `Templates` class is the main export of the `templates` library. All of the other classes are exposed as static properties on `Templates`:

- [Item](): Collection item, powered by [vinyl-item][].
- [View](): Collection item, powered by [vinyl-view][].
- [List]()
- [Views]():
- [Collection](): Base collections class. Use this if you need to customize the render cycle, middleware stages, and so on.
- [Group]()

{%= apidocs("index.js", {appname: 'app', ctor: 'templates'}) %}

***

### Engines
{%= apidocs("node_modules/base-engines/index.js") %}

***

### Helpers
{%= apidocs("node_modules/base-helpers/index.js", {appname: 'app'}) %}

### Built-in helpers
{%= apidocs("lib/helpers.js", {appname: 'app'}) %}

***

### View
API for the `View` class.

{%= apidocs("node_modules/vinyl-view/index.js") %}

#### View Data
{%= apidocs("lib/plugins/context.js", {appname: 'view'}) %}

***

### Item
API for the `Item` class.

{%= apidocs("node_modules/vinyl-item/index.js") %}

#### Item Data
{%= apidocs("lib/plugins/context.js", {appname: 'item'}) %}

***

### Views
API for the `Views` class.

{%= apidocs("lib/views.js") %}

#### Views Data
{%= apidocs("lib/plugins/context.js", {appname: 'views'}) %}


***

#### Lookup methods
{%= apidocs("lib/plugins/lookup.js") %}


***

### Collections
API for the `Collections` class.

{%= apidocs("lib/collection.js") %}
{%= apidocs("lib/plugins/context.js", {appname: 'collection'}) %}

***

### List
API for the `List` class.

{%= apidocs("lib/list.js") %}
{%= apidocs("lib/plugins/context.js", {appname: 'list'}) %}

***

### Group
API for the `Group` class.

{%= apidocs("lib/group.js") %}

***

### Lookups
{%= apidocs("lib/plugins/lookup.js") %}

***

### Rendering
{%= apidocs("lib/plugins/render.js") %}

***

### Context
{%= apidocs("lib/plugins/context.js", {appname: 'app'}) %}

***

### Middleware
Control the entire render cycle, with simple-to-use routes and middleware.

{%= apidocs("node_modules/base-routes/index.js") %}

***

### is
{%= apidocs("lib/plugins/is.js") %}

***

## More examples

This is just a very basic glimpse at the `templates` API!

```js
var templates = require('templates');
var app = templates();

// create a collection
app.create('pages');

// add views to the collection
app.page('a.html', {content: 'this is <%= foo %>'});
app.page('b.html', {content: 'this is <%= bar %>'});
app.page('c.html', {content: 'this is <%= baz %>'});

app.pages.getView('a.html')
  .render({foo: 'home'}, function (err, view) {
    //=> 'this is home'
  });
```

## History
{%= changelog('changelog.md') %}