verb NPM version Build Status

Verb makes it easy to build project documentation using simple markdown templates, with zero configuration required.

Wondering what happened to Phaser? Get the story.

Install

Install with npm

npm i -g verb --save-dev

Now that verb is installed, add README.tmpl.md to the docs/ dir in your project (this is all customizable, but let's keep it simple here), and add this to the file:

# {%= name %}

> {%= description %}

### Getting started
Install with [npm](npmjs.org) `npm i -g {%= name %} --save-dev`

### Options
{%= docs("options") %}

### Examples
{%= docs("examples") %}

### Author
+ {%= author.name %}

### License
{%= copyright() %}
{%= license() %}

Next, run:

verb

That wasn't so hard, was it? (It was? Try downloading Verb instead) Please report any bugs or feature requests, thanks!

About

How does Verb work?

Upon running the docs command, unless instructed to do otherwise Verb will attempt to build any markdown templates found in the docs/ directory of your project, using the data from project's package.json as context.

For many users, Verb might only be used to build the readme for projects, so that project metadata such as version, date, changelog and so on, are always current and consistent. See the Verb generator for examples.

Beyond the basics

For users who want more than the basics, Verb is also highly configurable via options and offers an extensive API for developers who want to add functionality in the form of plugins, middleware, custom tags, filters and so on.

Why use Verb?

We all know that documenation can be one of the most challenging and time-consuming aspects of maintaining a project. Even for small projects, simply writing and organizing the content on a readme can take more time than it did to create the library itself.

Verb dramatically reduces the time and effort involved in maintaining markdown docs for code projects through the use of powerful utilities and tools, well-defined conventions, and sensible defaults that are specifically tuned to maintaining projects on GitHub.

For starters, this is accomplished by:

  1. Using templates for any sections or text than can be generaralize, such as badges, license, copyright, author, Table of Contents and so on.
  2. Allowing includes (partials) to be used, so that longer documents can be easily organized and broken down into logical topics or groupings.
  3. Pulling in data from package.json to pass as context to any templates. Custom data sources may be used as well.
  4. Using boilerplates to kickstart the documentation for new projects. The Verb generator for Yeoman comes with a handful of boilerplates, but it's super easy to create and use your own.

Ease of Use

Verb loves users

Verb's number one priorty is ease-of use. For new users zero configuration is required to get started. Once Verb is installed, simply enter docs in command line, and you're off and running.

For more experienced users, Verb offers more than 50 template tags and filters, includes and partial caching, comment parsing, YAML Front Matter (or Coffee Front Matter!), plugins, mixins, tons of helpful JavaScript and Node.js utilites, and lots more.

API

Verb also loves developers

Verb has an extensive API and tools for building plugins, custom tags and filters, or extending Verb in other ways.

Features

FAQ

Tests

Run the tests with:

mocha -R spec

Renamed from Phaser

Authors

Jon Schlinkert

Brian Woodward

License

Copyright (c) 2014 Jon Schlinkert, contributors. Released under the MIT license

This file was generated by Verb on March 14, 2014.