grunt-readme

Grunt plugin for generating a README from templates, including an optional table of contents. No Gruntfile config is necessary, just choose a starter template and you'll be ready to go.

Documentation → | Examples →

Please report any bugs or feature requests, thanks!

Quickstart

If you haven't used grunt before, be sure to check out the Getting Started guide.

From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:

npm install grunt-readme --save-dev

Once that's done, add this line to your project's Gruntfile:

grunt.loadNpmTasks('grunt-readme');

If the plugin has been installed correctly, run grunt readme at the command line. If the plugin has been installed properly, you should see a success message.

That's it! If you are happy with the defaults, no additional Gruntfile configuration is required.

Example "README" template

When you first add grunt-readme to a project, the task will automatically add a readme if it doesn't find one. But it's recommended that you customize you're own README template. Feel free to use any of the templates included in this repo, or copy/past the blow example into ./docs/README.tmpl.md:

# {%= name %}
 
> {%= description %}
 
{%= toc %}
 
## Overview
{%= _.doc("overview.md") %}
 
## Options
{%= _.doc("options.md") %}
 
## Examples
{%= _.doc("examples.md") %}
 
## License and Copyright
{%= copyright %}
{%= license %}

Then add overview.md, options.md and examples.md to the ./docs directory. Of course, all of this is completely optional.

Visit the full documentation → | See examples →

Release History

• 2013-11-15   v0.3.5   Repos task is now a separate grunt plugin. Adds basic badge mixins and lots of new test fixtures to test templates and mixins.
• 2013-11-15   v0.3.0   Updates function that reads in metadata from options to accept mixed formats.
• 2013-11-08   v0.2.4   Adds table of contents generation. Just use {%= toc %} where you want it to go.
• 2013-11-03   v0.2.2   Fixes the function for the metadata option. Externalizes advanced docs since no config is really needed for this task.
• 2013-10-11   v0.1.9   Adds ability to specify multiple metadata files in yaml or json format.
• 2013-09-21   v0.1.3   Completely refactored. Adds a lot of documentation.
• 2013-09-19   v0.1.0   First commmit.

Related Projects

Here are some related projects you might be interested in from the Assemble core team.

grunt-convert

Grunt task to convert to or from JSON, YAML, XML, PLIST or CSV.

grunt-firebase

Grunt task for updating firebase data.

grunt-github-api

Grunt plugin used to query the Github API and save the returned JSON files locally.

grunt-matter

Add, extend, sort, and strip YAML front matter. Also has options for populating randomized mock data.

grunt-repos

Use Grunt to pull down a list of repos from GitHub.

grunt-toc

Grunt plugin for generating a markdown Table of Contents (TOC).

Visit assemble.io/plugins for more information about Assemble plugins.

Contributing

Find a bug? Have a feature request? Please create an Issue.

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt, and build the documentation with grunt-readme.

Pull requests are also encouraged, and if you find this project useful please consider "starring" it to show your support! Thanks!

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

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

This file was generated by grunt-readme on Saturday, December 14, 2013.