verb

by verbose

verbose / verb

HEADS UP! Verb is going though a major transition, we've completely refactored everything from the g...

438 Stars 34 Forks Last release: Not found MIT License 828 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

verb NPM version Build Status

Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.

Built by verb

The follow projects use verb to build the reamde and other docs:

  • micromatch (1.7m downloads/mo) - this readme is pretty extensive, with a TOC and other advanced features
  • is-glob (1.6m downloads/mo) - example of simple readme
  • repeat-string (2.2m downloads/mo) - example of another basic readme.

Quickstart

Install

verb
and
verb-cli
globally:
$ npm i verb verb-cli -g

Next, just add a

.verb.md
markdown template to your project and run
verb
in the commandline (NOTE that verb will overwrite the existing
README
, so make sure your work is committed!)
.

I'm working on a site for verb, but in the meantime a good place to see

.verb.md
examples is to surf my projects.

Install

Install with npm

$ npm i verb --save-dev

Usage

var verb = require('verb');

Table of contents

(Table of contents generated by [verb])

Features

  • Generate markdown docs, or HTML
  • Generate a Table of Contents simply by adding
     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

(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

.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('./'));
});

.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']);
});

.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');
});

.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);
});

Related projects

  • assemble: Static site generator for Grunt.js, Yeoman and Node.js. Used by Zurb Foundation, Zurb Ink, H5BP/Effeckt,… more | homepage
  • composer: API-first task runner with three methods: task, run and watch. | homepage
  • engine: Template engine based on Lo-Dash template, but adds features like the ability to register helpers… more | homepage
  • template: Render templates using any engine. Supports, layouts, pages, partials and custom template types. Use template… more | homepage

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.

Troubleshooting

  1. First things first, please make sure to run
    npm cache clear
    , then do
    npm i verb verb-cli -g
    . If that doesn't clear things up, try #2.
  2. Create an issue. We'd love to help, so please be sure to provide as much detail as possible, including:
  • version of verb and verb-cli
  • platform
  • any error messages or other information that might be useful.

Major changes

Author

Jon Schlinkert

License

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


This file was generated by verb-cli on August 26, 2015.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.