README
verb
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
<!-- 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
(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 namefn
{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 tosrc
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 todest
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 isdiffJson
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
- First things first, please make sure to run
npm cache clear
, then donpm i verb verb-cli -g
. If that doesn't clear things up, try #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
v0.4.0
: Verb now requires verb-clito run. See the getting started section for details.
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.