Repository files navigation

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

Installverb andverb-cli globally:

$ npm i verb verb-cli -g

Next, just add a.verb.md markdown template to your project and runverb in the commandline(NOTE that verb will overwrite the existingREADME, 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 surfmy projects.

Install withnpm

$ npm i verb --save-dev

varverb=require('verb');

• Features

• CLI

• API

  • Template API
  • Config API
  • Data API
  • Middleware API
  • Task API
  • .task
  • .watch

• Related projects

• Why use Verb?

• Running tests

• Contributing

• Troubleshooting

• Major changes

• Author

• License

(Table of contents generated by [verb])

• 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'sdocs/ directory with the{%= docs() %} helper
• Change the templates directory for either helper by passing acwd to the helper: example:{%= docs("foo", {cwd: ''}) %}

(WIP)

Verb's API is organized into the following categories:

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

(WIP)

Methods:

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

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

Transforms

Run immediately during init. Used to extend or modify thethis object.

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

Application Settings

Set arbitrary values onverb.cache:

• .set
• .get
• .del

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

Options

Set and get values fromverb.options:

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

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

(WIP)

Set and get values fromverb.cache.data

• .data

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

(WIP)

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

(WIP)

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

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

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 tosrc plugins

Example

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

Specify a destination for processed files.

Params

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

Example

verb.dest('dist')

Copy aglob of files to the specifieddest.

Params

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

Example

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

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

Params

• a{Object|String}
• b{Object|String}
• methodName{String}: Optionally pass ajsdiffmethod name to use. The default isdiffJson

Example

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

• 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

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.

Install dev dependencies:

$ npm i -d&& npmtest

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

1. First things first, please make sure to runnpm cache clear, then donpm i verb verb-cli -g. If that doesn't clear things up, try #2.
2. Createan 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.

• v0.4.0: Verb now requiresverb-clito run. See thegetting started section for details.

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Copyright © 2014-2015Jon SchlinkertReleased under the MIT license.

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