Skip to content

Latest commit

 

History

History
250 lines (161 loc) · 5.58 KB

.verb.md

File metadata and controls

250 lines (161 loc) · 5.58 KB

What is this?

This is a plugin for [verb][], for automatically generating a README.md file using

Why use this?

Encourages readme-driven development!

Heads up!

This generator requires verb 0.9.0 and up, which is currently on the dev branch. If you're willing to put up with occassional bugs and would like to provide helpful feedback, install verb with the following command:

$ npm install --global "verbose/verb#dev"

What is verb?

Verb is a powerful, open-source developer framework and documentation build-system for GitHub projects.

API

Built on node.js, Verb's API is crafted around the purpose of simplifying how documentation is specified, authored, rendered and generated. The core verb application offers methods for rendering templates, working with the file system, registering and running tasks, and verb can be extended to do anything else using plugins.

CLI

Once installed globally, verb's CLI is run using the verb command.

verbfile.js

Each time the verb command is run, verb's CLI looks for a verbfile.js in the user's current working directory and if found will try to load the file and execute any [tasks]({%= verb.repo %}#tasks) specified by the user.

.verb.md

If {%= name %} is installed (locally or globally), and a verbfile.js is not found, verb's CLI looks for a .verb.md readme template in the user's current working directory. If found, verb will render the file to create a README.md using data from the user's environment, such as package.json and .git config (for username, if necessary).

Visit the [verb][] project to learn more.

Getting started

Installing the CLI

To run the {%= alias %} generator from the command line, you'll need to first install [verb][] globally first. You can that now with the following command:

$ npm install --global verb

This adds the verb command to your system path, allowing it to be run from any directory. Visit the [verb][] project and documentation to learn more.

Run the {%= alias %} generator from the command line

Once both [verb][] and {%= name %} are installed globally, you can run the generator with the following command:

Run the {%= alias %} generator from the command line:

$ verb {%= alias %}

Command line

Tasks

The following tasks are defined on {%= name %}.

{%= increaseHeadings(apidocs('*.js')) %}

Options

Configuration options can be:

  • passed on the command line
  • defined on the verb object in package.json, or
  • set directly [using the API][docs]{api/options.md}

Most of the following examples show how to set configuration values on the verb object via the command line, but you can also set these manually.

run

To automatically run the readme generator with the verb command (without specifying readme on the command line), add the following to package.json:

// --package.json--
{
  // add a verb object with an array of tasks to run
  "verb": {
    "tasks": ["readme"]
  }
}

silent

Mute progress for tasks and generators from being displayed in the terminal.

CLI

$ verb --silent

verb config

In your project's package.json:

{
  "verb": {
    "silent": true
  }
}

API

In your verbfile.js or application code:

app.enable('silent');

// equivalent to
app.option('silent', true);

Examples

running tasks and generators

With --silent

running tasks and generators with the silent flag

readme

Customize the location of your readme template.

CLI

$ verb --readme="lib/foo.md"

verb config

In your project's package.json:

{
  "verb": {
    "readme": "docs/foo.md"
  }
}

times

Display all timings that are typically muted in the terminal.

CLI

$ verb --times

verb config

Always show timings for a project by adding the following to package.json:

{
  "verb": {
    "times": true
  }
}

API

In your verbfile.js or application code:

app.enable('times');
// equivalent to
app.option('times', true);

toc

Disable or enable the Table of Contents in the built-in layouts:

CLI

Set in-memory options for the current run only:

# enable
$ verb --toc
# disable
$ verb --toc:false

Persist options to package.json:

# enable
$ verb --config=toc
# disable
$ verb --config=toc:false

Results in:

{
  "name": "my-project",
  "verb": {
    "toc": false
  }
}

no-reflinks-cache

Disable reflinks caching.

$ verb --no-reflinks-cache

layout

Set the layout to use for a project.

$ verb --config=layout:default

Available layouts

As with all templates, you can easily override these and/or define your own templates in a verbfile.js. Verb does much more than generate readme's!

The following layouts are available:

  • default: a layout with installation, tests, author, usage, related list, contributing and license sections.
  • global: same as default, but with global npm installation instructions ({%= name %} uses this layout)
  • empty: noop layout. no content is applied, but all layout-related middleware stages will still run.

Layouts can be defined on a template-by-template basic, and even for includes. If you need more granularity just add a verbfile.js with your custom code.

[docs]: {%= platform.docs %}/