a.md

Verb Tags

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

Built-in tags

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

badge

Example:

{%%= badge() %}

changelog()

Use data from CHANGELOG in the root of a project to generate a formatted markdown changelog.

Usage:

{%%= changelog() %}

Results in:

## Release History

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

Features

• Columns are formatted using columnify
• Dates are parsed by moment.js

Custom data source

Use a custom data source, formatted as valid YAML or JSON.

Usage:

{%%= changelog('history.yml') %}

Data format

In CHANGELOG, or if you supply a custom data source, please use the following conventions:

YAML format:

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

JSON format:

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

contrib( filepath )

Used by the Assemble core team, retrieves and includes a template from verb-contrib-templates.

Usage:

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

Results in:

**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()

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

Usage:

{%%= copyright() %}

Results in:

Copyright (c) 2014 Jon Schlinkert, contributors.

date( format )

Format a date using moment.js

Usage:

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

Returns

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

Consult the moment.js documentation for the full list of available options.

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

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

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

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

```bash
npm i  {%%= name %} --save-dev
```

Resulting in this.

getAuthors()

Example:

{%%= getAuthors() %}

html( filepath )

Example:

{%%= html() %}

include( filepath, options )

Include a generic template from verb-readme-includes. The include tag is great for allowing docs to be reused across multiple projects, or just to organize.

Usage:

{%%= 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).

license()

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

Usage:

{%%= license() %}

Returns:

Released under the MIT license

log( string )

Usage:

{%%= log() %}

methods( filepath, options )

Params:

• filepath (required). default: undefined

Uses 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:

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

Results in:

## foo
Type: `undefined`

Default: `undefined`

## bar
Type: `undefined`

Default: `undefined`

## baz
Type: `undefined`

Default: `undefined`

Specify a template to use.

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

Visit list-methods to see all available options.

moment

Usage:

{%%= moment() %}

raw( filepath )

Params:

• filepath (required)

Usage:

{%%= raw() %}

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:

# Table of Contents

{%%= toc() %}

Results in something like:

# Table of Contents

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

Experimental tags

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

comments( filepath )

Usage:

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

authors

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

Usage:

{%%= authors() %}

Results in:

[
  {
    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.

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:

{
  "name": "Bar"
}

we would use it like this:

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

resulting in:

Bar