> Built-in tags provided by Verb

Verb "tags" are just Lo-Dash templates, which means you have the power of straight JavaScript in your templates.

Verb offers a number of specialized tags that were created to address common needs, but it's easy to [add your own custom tags](#custom-tags) too.

## Built-in tags

The following tags can be used in templates out-of-the-box:

### badge

Example:

```js
{%%= badge() %}
```

### changelog

```
changelog()
```

Automatically use data from a valid, YAML-formatted [CHANGELOG](./CHANGELOG) file in the root of a project to generate a markdown changelog.

Usage:

```js
{%%= changelog() %}
```

Results in:

```
## Release History

**DATE**       **VERSION**   **CHANGES**
* 2014-03-10   v0.1.0        First commmit.
```

**Features**

* Columns are formatted using [columnify](https://github.com/timoxley/columnify)
* Dates are parsed by [moment.js](momentjs.com/docs/)


**Custom data source**

Optionally pass in the filepath of a different JSON or YAML data file to use:

```js
{%%= changelog("history.yml") %}
```

**Example data**

In [CHANGELOG](./CHANGELOG), or if you supply a custom data source, please use the following conventions:

YAML format:

```yaml
v0.1.0:
  date: 2014-03-11
  changes:
    - First commmit.
```

JSON format:

```json
{
  "v0.1.0": {
    "date": "2014-03-11",
    "changes": [
      "First commmit."
    ]
  }
}
```

### contrib

```
contrib( filepath )
```

Used by the Assemble core team, includes a template from [verb-contrib-templates](https://github.com/assemble/verb-contrib-templates).

Usage:

```js
{%%= contrib('authors') %}
```

Results in:

```bash
**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

**Brian Woodward**

+ [github/doowb](https://github.com/doowb)
+ [twitter/doowb](http://twitter.com/jonschlinkert)
```

### copyright

```
copyright()
```

Return a copyright statement, automatically populated with data from package.json.

Usage:

```js
{%%= copyright() %}
```

Results in:

```
Copyright (c) 2014 Jon Schlinkert, contributors.
```

**Start year**

Optionally pass in the start year of your project.

Type: `string`

Default: `undefined`

Example:

```js
{%%= copyright('2010') %}
```

Results in:

```
Copyright (c) 2010-2014 Jon Schlinkert, contributors.
```

### date

```
date( format )
```

Format a date using [moment.js](momentjs.com/docs/)

Usage:

```js
{%%= date('YYYY-MM-DD') %}
```

Returns

<!-- don't escape this template! -->

```js
{%= date('YYYY-MM-DD') %}
```

Consult the [moment.js documentation](momentjs.com/docs/) for the full list of available options.

### docs

```
docs( filepath, options )
```

**filepath**

The path to the file you want to include in the `docs/` directory

**Options**

* `docs`: the directory to search when using the `{%%= docs() %}` tag.
* `ext`: the file extension to use. Default `.md`.

**Usage**

```js
{%%= docs('install') %}
```

Adds the contents of `docs/install.md`, which might look like:

<pre>
Install globally with [npm](npmjs.org):

```bash
npm i  {%%= name %} --save-dev
```
</pre>

[Resulting in this](./README.md/#install).


### getAuthors

```
getAuthors()
```

_(TODO)_

Example:

```js
{%%= getAuthors() %}
```

### html

```
html( filepath )
```

_(TODO)_

Example:

```js
{%%= html() %}
```

### include

```
include( filepath, options )
```

Include a _generic_ template from [verb-readme-includes](https://github.com/assemble/verb-readme-includes). The `include` tag is great for allowing docs to be reused across multiple projects, or just to organize.

Usage:

```js
{%%= include('footer.md') %}
```
Results in:

```
_This file was generated by [verb](https://github.com/assemble/verb) on March 22, 2014._
```
_(Note that the name and url can be automatically updated by the [current runner](#verb-runner))._

### license

```
license()
```

Return a "license" statement, populated with data from package.json.

Usage:

```js
{%%= license() %}
```

Returns:

```
Released under the MIT license
```

### log

```
log( string )
```

_(TODO)_

Usage:

```js
{%%= log() %}
```

### methods

```
methods( filepath, options )
```

Params:

* `filepath` (required). default: `undefined`

Uses [list-methods](https://github.com/jonschlinkert/list-methods) to list the property names of all enumerable properties, own and inherited, of objects that have function values.
In other words, this tag can help kickstart your API documentation!

Usage:

```js
{%%= methods('foo.js') %}
```

Results in:

```yaml
## foo
Type: `undefined`

Default: `undefined`

## bar
Type: `undefined`

Default: `undefined`

## baz
Type: `undefined`

Default: `undefined`
```

Specify a template to use.

```js
{%%= methods('foo.js', {template: 'yaml'}) %}
```

Visit [list-methods](https://github.com/jonschlinkert/list-methods) to see all available options.

### moment

```
moment()
```

_(TODO)_

Usage:

```js
{%%= moment() %}
```

### raw

```
raw( filepath )
```

_(TODO)_

Params:

* `filepath` (required)

Usage:

```js
{%%= raw() %}
```

### toc

```
toc( filepath )
```

Params:

* `filepath` (optional): the file path or globbing patterns for the files that you want to generate a TOC for.

If left undefined, a table of contents is generated for the current page.

Usage:

```js
# Table of Contents

{%%= toc() %}
```

Results in something like:

```
# Table of Contents

* [Install](#install)
* [Customize](#customize)
* [Test](#test)
* [Contribute](#contribute)
* [Author](#author)
* [License](#license)
```

Also see [Generating a TOC](#generating-a-toc).

## Experimental tags

These tags can be used, but they require more testing in different scenarios before they can be considered stable:


### comments

```
comments( filepath )
```

_(TODO)_

Usage:

```js
{%%= comments('foo/*.js') %}
```

### authors

Parses the `AUTHORS` file in the root of a project and returns an array of authors.

Usage:

```js
{%%= authors() %}
```
Results in:

```js
[
  {
    name: 'Jon Schlinkert'
    email: '',
    url: 'https://github.com/jonschlinkert'
  },
  {
    name: 'Brian Woodward'
    email: '',
    url: 'https://github.com/doowb'
  }
]
```

### Custom tags

Verb "tags" are just JavaScript functions processed by lodash.template. So you have the power of straight JavaScript in your templates, with the ease-of-use and metadata supplied by Verb. This example shows how easy it is to create a custom tag for Verb.

```js
module.exports = function(verb) {
  var tags = {};

  /**
   * Retrieve a value from the specified json file
   * Usage: {%%= foo('name') %}
   */

  tags.foo = function(val) {
    var data = verb.file.readJSONSync('foo.json');
    return data[val];
  };
  return tags;
};
```

Given that `foo.json` has:

```json
{
  "name": "Bar"
}
```
we would use it like this:

```js
{%%= foo('name') %}
```

resulting in:

```
Bar
```