assemble/verb — pull request #26 by jonschlinkert (2014-11-10 23:41:48+00:00)
Title: V0.3.0

Complete refactor, built on top of [template](https://github.com/jonschlinkert/template), [orchestrator](https://github.com/orchestrator/orchestrator) (temporarily), [vinyl-fs](https://github.com/wearefractal/vinyl-fs), and borrows some code from gulp for the CLI.

For the most part, verb documentation, and the conventions used will stay the same, like template formats and so on. However, there are a few major changes:

## Major changes

### API

Verb v0.3.0 is based on [template](https://github.com/jonschlinkert/template), so all Template methods are exposed on verb. For example, to load data, do:

```js
verb.data({foo: 'bar'});
// or
verb.data('foo/*.json');
```
See [template](https://github.com/jonschlinkert/template) for more API details.

### verbfiles

- `.verbrc.md` is being deprecated in favor of `.verb.md`. Projects that use `.verbrc.md` won't break, so you can transition when it makes sense.
- in addition to `.verb.md` you can also (or alternatively) use a `verbfile.js`.
- you can use gulp plugins in your verbfile.js, using the same conventions as gulp.

This powerful combination allows you to easily kickstart projects with a `.verb.md` when all you need is a README template or basic docs, but when you need to build more complex documentation you can add a `verbfile.js`, along with any plugins, engines, helpers, middleware, transforms or any other extensions/conventions supported by [template](https://github.com/jonschlinkert/template) and vinyl-fs.

**Example**

```js
var verb = require('verb');
// load data to pass to templates
verb.data('foo.json');

verb.task('default', function() {
verb.src('docs/*.md')
.pipe(verb.dest('./'));
});
```

### Helpers
> `tags` are now `helpers`

**Auto-loading**

Custom helpers are just regular javascript functions. If you want to use custom helpers in your `.verb.md` files, verb will load them automatically if you use the naming convention `helper-foo`, and be sure to add the helper to the `dependencies` or `devDependencies` in package.json.

**Manual**

if your project has a `verbfile.js`, helpers can be registered using the `.helper()` method:

```js
var verb = require('verb');

// add a helper to be used in templates
verb.helper('uppercase', function(str) {
return str.toUpperCase();
});

verb.task('default', function() {
verb.src('.verb.md')
.pipe(verb.dest('./'));
});
```

## Misc

By default, verb will rename the dest for a `.verbrc.md` or `.verb.md` file to `README.md`. If you don't want this behavior, just disable it:

```js
verb.disable('dest:readme plugin');
```