verb

verb

Documentation generator for GitHub projects. Extremely powerful, easy to use, can generate anything from API docs to a readme, for projects big or small.

Verb is the most powerful, extensible and easy-to-use documentation generator for node.js.

Install

Install with npm

$ npm i verb --save-dev

Usage

var verb = require('verb');

Features

• Generate markdown docs, or HTML
• Generate a Table of Contents simply by adding <!-- toc --> to any document.
• Include templates from locally installed npm packages with the {%= include() %} helper
• Include templates from your project's docs/ directory with the {%= docs() %} helper
• Change the templates directory for either helper by passing a cwd to the helper: example: {%= docs("foo", {cwd: ''}) %}

CLI

(WIP)

API

Verb's API is organized into the following categories:

• Template API
• Config API
• Data API
• Middleware API
• Task API

Template API

(WIP)

Methods:

• .create
• .loader
• .load
• .engine
• .helper
• .helpers
• .asyncHelper
• .asyncHelpers
• .render

Verb exposes entire API from template. See the [template docs] the full API.

Config API

Transforms

Run immediately during init. Used to extend or modify the this object.

verb.transform('engine', function() {
  this.engine('md', require('engine-lodash'));
});

Application Settings

Set arbitrary values on verb.cache:

• .set
• .get
• .del

See the [config-cache docs] the full API.

Options

Set and get values from verb.options:

• .option
• .enable
• .enabled
• .disable
• .disabled
• .disabled

See the [option-cache docs] the full API.

(WIP)

Data API

Set and get values from verb.cache.data

• .data

Verb exposes entire API from plasma. See the [plasma docs] the full API.

(WIP)

Middleware API

Verb exposes the entire [en-route] API. See the [en-route docs] the full API.

(WIP)

Task API

.src

Glob patterns or filepaths to source files.

Params

• glob {String|Array}: Glob patterns or file paths to source files.
• options {Object}: Options or locals to merge into the context and/or pass to src plugins

Example

verb.src('src/*.hbs', {layout: 'default'})

.dest

Specify a destination for processed files.

Params

• dest {String|Function}: File path or rename function.
• options {Object}: Options and locals to pass to dest plugins

Example

verb.dest('dist')

.copy

Copy a glob of files to the specified dest.

Params

• glob {String|Array}
• dest {String|Function}
• returns {Stream}: Stream, to continue processing if necessary.

Example

verb.task('assets', function() {
  verb.copy('assets/**', 'dist');
});

.task

Define a Verb task.

Params

• name {String}: Task name
• fn {Function}

Example

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

.getCollection

Get a view collection by it's singular or plural name (e.g. "page" or "pages").

• returns {String} name: Singular name of the collection to get

Example

var collection = verb.getCollection('pages');
// gets the `pages` collection
//=> {a: {}, b: {}, ...}

.diff

Display a visual representation of the difference between two objects or strings.

Params

• a {Object|String}
• b {Object|String}
• methodName {String}: Optionally pass a jsdiffmethod name to use. The default is diffJson

Example

var doc = verb.views.docs['foo.md'];
verb.render(doc, function(err, content) {
  verb.diff(doc.orig, content);
});

.watch

Re-run the specified task(s) when a file changes.

Params

• glob {String|Array}: Filepaths or glob patterns.
• fn {Function}: Task(s) to watch.

Example

verb.task('watch', function() {
  verb.watch('docs/*.md', ['docs']);
});

Related projects

• en-route: Routing for static site generators, build systems and task runners, heavily based on express.js routes… more
• template: Render templates using any engine. Supports, layouts, pages, partials and custom template types. Use template… more

Why use Verb?

It's magical and smells like chocolate. If that's not enough for you, it's also the most powerful and easy-to-use documentation generator for node.js. And it's magical.

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Major changes

• v0.4.0: Verb now requires verb-clito run. See the getting started section for details.

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2014-2015 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb-cli on May 18, 2015.