generate-readme
Generate a README.md using answers to prompts and data from the environment, like package.json
, .git
config, etc. This generator can be run by command line if Generate is installed globally, or you can use this as a plugin or sub-generator in your own generator.
TOC
- What is "Generate"?
- Command line usage
- Tasks
- Running multiple generators
- API usage
- Customization
- About
(TOC generated by verb using markdown-toc)
Example
Templates are customizable and can be overridden.
What is "Generate"?
Generate is a command line tool and developer framework for scaffolding out new GitHub projects using generators and tasks. Answers to prompts and the user's environment can be used to determine the templates, directories, files and contents to build. Support for gulp, base and assemble plugins, and much more.
For more information about Generate:
- Visit the generate project
- Visit the generate documentation
- Find generators on npm (help us author generators)
Command line usage
Install globally
Installing the CLI
To run the readme
generator from the command line, you'll need to install generate globally first. You can do that now with the following command:
$ npm install --global generate
This adds the gen
command to your system path, allowing it to be run from any directory.
Install generate-readme
You may now install this module with the following command:
$ npm install --global generate-readme
Running generate-readme
You should now be able to run generate-readme
with the following command:
$ gen readme
What will happen?
Running $ gen readme
will run the generator's default task, which will:
- prompt you for any information that's missing
- render the file using your answers
- generate the readme to the current working directory.
Conflict detection
This generator will prompt you for feedback before overwrite existing files. You can set the destination to a new directory if you want to avoid the prompts, or avoid accidentally overwriting files with unintentional answers => 'Oops! I meant "no!"'.
What you should see in the terminal
If completed successfully, you should see both starting
and finished
events in the terminal, like the following:
[00:44:21] starting ...
...
[00:44:22] finished ✔
If you do not see one or both of those events, please let us know about it.
Help
To see a general help menu and available commands for Generate's CLI, run:
$ gen help
Running tasks
Generators use tasks for flow control. Tasks are run by passing the name of the task to run after the generator name, delimited by a comma.
Example
For instance, the following will run generator readme
, task bar
:
$ gen readme:foo
^ ^
generator task
Default task
If a task is not explicitly passed Generate's CLI will run the default
task.
Tasks
readme:readme
Generate a README.md
in the current working directory.
Example
$ gen readme:readme
Visit Generate's documentation for tasks.
Running multiple generators
Generate supports running multiple generators at once. The following generator(s) work well with generate-readme
:
generate-dest
Run generate-dest before generate-readme
to prompt for the destination directory to use for generated files.
$ gen dest readme
Example
API usage
Use generate-readme
as a plugin in your own generator.
Install locally
Install with npm:
$ npm install --save generate-readme
Register as a plugin
Inside your own generator:
module.exports = function(app) {
// register generate-readme as a plugin
app.use(require('generate-readme'));
};
Run tasks
Programmatically run tasks from generate-readme
:
module.exports = function(app) {
// register generate-readme as a plugin
app.use(require('generate-readme'));
// run the `default` task on generate-readme
app.task('foo', function(cb) {
app.generate('generate-readme', cb);
});
// or run a specific task on generate-readme
// (where `foo` is the name of the task to run)
app.task('bar', function(cb) {
app.generate('generate-readme:foo', cb);
});
};
Visit the generator docs to learn more about creating, installing, using and publishing generators.
Customization
The following instructions can be used to override settings in generate-readme
. Visit the Generate documentation to learn about other ways to override defaults.
Destination directory
To customize the destination directory, install generate-dest globally, then in the command line prefix dest
before any other generator names.
For example, the following will prompt you for the destination path to use, then pass the result to generate-readme
:
$ gen dest readme
Overriding templates
You can override a template by adding a template of the same name to the templates
directory in user home.
For example, to override the package.json
template, add a template at the following path ~/generate/generate-readme/templates/README.md
, where ~/
is the user-home directory that os.homedir()
resolves to on your system.
About
Related projects
You might also be interested in these projects:
- generate-gitignore: Generate a .gitignore file from the command line when Generate's CLI is installed globally, or… more | homepage
- generate-license: Generate a license file for a GitHub project. | homepage
- generate-package: Generate a package.json from a pre-defined or user-defined template. This generator can be used from… more | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running tests
Install dev dependencies:
$ npm install -d && npm test
Author
Jon Schlinkert
License
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb, v0.9.0, on July 09, 2016.