verb
Version:
A project without documentation is like a project that doesn't exist. Verb solves this by making it dead simple to generate docs, using simple markdown templates, with zero configuration required.
486 lines (320 loc) • 6.9 kB
Markdown
> 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
```