Newlywed Party Monsters

    verb-generate-readme

    0.8.0 • Public • Published

    verb-generate-readme NPM version NPM monthly downloads NPM total downloads Linux Build Status

    Generate your project's readme with verb. Requires verb v0.9.0 or higher.

    You might also be interested in generate.

    Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

    Table of Contents

    Details

    (TOC generated by verb using markdown-toc)

    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 specified by the user.

    .verb.md

    If verb-generate-readme 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 readme 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 readme generator from the command line

    Once both verb and verb-generate-readme are installed globally, you can run the generator with the following command:

    Run the readme generator from the command line:

    $ verb readme

    Command line

    Tasks

    The following tasks are defined on verb-generate-readme.

    default

    Alias for the readme task, generates a README.md to the user's working directory.

    Example

    $ verb readme

    readme

    Generate README.md and fix missing reflinks.

    Example

    $ verb readme

    Options

    Configuration options can be:

    • passed on the command line
    • defined on the verb object in package.json, or
    • set directly using the API

    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 (verb-generate-readme 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.

    About

    Contributing

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

    Running Tests

    Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test
    Building docs

    (This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

    To generate the readme, run the following command:

    $ npm install -g verbose/verb#dev verb-generate-readme && verb

    Related projects

    You might also be interested in these projects:

    • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
    • generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
    • update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… more | homepage
    • verb-collections: Verb plugin that adds includes, layouts, badges and docs template collections. Can be used with… more | homepage
    • verb-repo-data: Verb plugin that adds repository and package.json data to the context for rendering templates. | homepage
    • verb-toc: Verb plugin that adds middleware for creating and injecting a table of contents into a… more | homepage
    • verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

    Contributors

    Commits Contributor
    245 jonschlinkert
    5 doowb
    2 olstenlarck
    1 ierceg
    1 arrowrowe

    Author

    Jon Schlinkert

    License

    Copyright © 2018, Jon Schlinkert. Released under the MIT License.


    This file was generated by verb-generate-readme, v0.6.0, on August 09, 2018.

    Install

    npm i verb-generate-readme

    DownloadsWeekly Downloads

    1,415

    Version

    0.8.0

    License

    MIT

    Unpacked Size

    147 kB

    Total Files

    101

    Last publish

    Collaborators

    • jonschlinkert