node package manager


grunt-readme NPM version

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!


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:


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/

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

Then add, and 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 NPM version

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

grunt-firebase NPM version

Grunt task for updating firebase data.

grunt-github-api NPM version

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

grunt-matter NPM version

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

grunt-repos NPM version

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

grunt-toc NPM version

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

Visit for more information about Assemble plugins.


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!


Jon Schlinkert

Brian Woodward


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

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