_                
                             (_)               
  __ _ _ __   ___  _ __ __  ___                
 / _` | '_ \ / _ \| '_ \\ \/ / |               
| (_| | |_) | (_) | | | |>  <| |               
 \__,_| .__/ \___/|_| |_/_/\_\_|               
      | |                                      
      |_|                                      
    ______               ____  ___                 
    | ___ \             | |  \/  |                 
    | |_/ /___  __ _  __| | .  . | ___             
    |    // _ \/ _` |/ _` | |\/| |/ _ \            
    | |\ \  __/ (_| | (_| | |  | |  __/            
    \_| \_\___|\__,_|\__,_\_|  |_/\___|            
                                                   
                                                   
         _____                           _             
        |  __ \                         | |            
        | |  \/ ___ _ __   ___ _ __ __ _| |_ ___  _ __ 
        | | __ / _ \ '_ \ / _ \ '__/ _` | __/ _ \| '__|
        | |_\ \  __/ | | |  __/ | | (_| | || (_) | |   
         \____/\___|_| |_|\___|_|  \__,_|\__\___/|_|   
                                                       
                                               

Grunt ReadMe Generator

A grunt task to generate a dynamic readme.md from partial markdown files in readme folder.

Jump to Section

• Getting Started
• Usage
• Options
• Release History
• Legal Mambo Jambo
• Tip Me
• Donate Me!

Getting Started

[Back To Top]

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-readme-generator --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-readme-generator');

## Usage
[[Back To Top]](#grunt-readme-generator)

In your project's Gruntfile, add a section named `readme_generator` to the data object passed into `grunt.initConfig()`.

```js
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  readme_generator: {
    options: {
      // Task-specific options go here.
      // detailed explanation is under options
      readme_folder: "readme",
      output: "README.md",
      table_of_contents: true,
      toc_extra_links: [],
      generate_changelog: false,
      changelog_folder: "changelogs",
      changelog_version_prefix: "",
      changelog_insert_before: "",
      banner: null,
      has_travis: true,
      github_username: "aponxi",
      generate_footer: true,
      generate_title: true,
      package_name: "",
      package_desc: "",
      informative: true
    },
    order: {
      // Title of the piece and the File name goes here
      // like so
      "installation.md": "Installation",
      "usage.md": "Usage",
      "options.md": "Options",
      "example.md": "Example",
      "output.md": "Example Output",
      "building-and-testing.md": "Building and Testing",
      "legal.md": "Legal Mambo Jambo"
    },
  },
})

• You provide with markdown files and the titles in the order object which has the format of file : title
• It generates the readme by iterating through that array in the given order
• In the example "building-and-testing.md": "Building and Testing" it is going to create a section called Building and Testing, making it a title; then it will read building-and-testing.md file from the readme directory set in readme_folder option and insert it after the title.
• Meaning that you shouldn't have titles in your seperate markdown files or in building-and-testing.md for the above example. They are automatically generated from the title.

To test use grunt test command and look at the outputs under test/ folder.

Options

[Back To Top]

Notes on the features

• Every folder name you provide is relative to the Gruntfile location, which is the root of your project
• If you see on/off yes/no that is true/false in CoffeeScript
• This readme has been generated by this plugin. Therefore the readme folder and the Gruntfile or Gruntfile.coffee of this project are great examples. Also you can check out the test folder folder.

readme_folder

the folder where readme partial files are located

• This is the folder where markdown files are located. These markdown files can have any file extension and will be appended into the README.MD file that will be generated.
• As an example I use "/readme" folder in my project directory and it has "banner.md", "legal.md", "options.md" etc. as seen under readme folder.

readme_folder: "readme" 

output

where readme file should be generated in respect to Gruntfile location

• You can name your generated readme file here.
• You can also provide a location which will be in respect to the root of the project
• For example I did /test/readme_no_banner.md to generate a readme with the banner option off to test, amongst other readme files.
• This is good to have when you are working with multiple generated markdown files.
• A good example can be seen on the Gruntfile or the default is:

output: "README.md" 

table_of_contents

generate automatic table of contents

• This generates automatic table of contents
• After each title for a section it will generate Back To Top links to navigate to the top
• This is either on/off (coffeescript) or true/false (javascript)
• Default is on

table_of_contents: on

toc_extra_links

Sometimes I like adding quick-links on the top in table of contents. Table of contents (TOC) must be enabled for this option to matter

• This adds extra links to the table of contents
• The need for this was to add a donation link, or link to issues page. Which is something that doesn't belong anywhere else than some navigation bar.
• You supply it with an array of the exact text you want on there. It copy pastes exactly what's written, doesn't auto-formats like it does when generating the table of contents from files provided.
• What I use for my purposes is donation links and they are like so:

toc_extra_links: [
    "[Tip Me ![](http://i.imgur.com/C0P9DIx.gif?1)](https://www.gittip.com/aponxi/)"
    "[Donate Me! ![](http://i.imgur.com/2tqfhMO.png?1)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=VBUW4M9LKTR62)"
    ]

• However, it is an empty array by default

toc_extra_links: [] 

generate_changelog

generates automatic changelog

• This feature adds the latest changelog from the folder that you write your markdown formatted changelog files and inserts it in the readme file. I usually have so many logs that I just want to add the latest changes in the Readme file.
• It sorts the changelog files found alphabetically to tell which one is the newest
• Check out changelogs folder folder to reference formatting
• Files can have a prefix if you want to eliminate old changelogs from being processed. To do so refer to the changelog_version_prefix option.
• Usually files are named such as 0.1.2.md, 0.11.0.markdown, 1.0.0.mdown etc
• This feature is either on or off (true/false for javascript)
• Important: If this feature is on, then you must have some changelog files under your changelog folder
• By default it is off:

generate_changelog: off 

changelog_folder

where changelog files are located

• If you keep your changelogs in a folder, specify it here
• It is a string of the folder name in respect to the project root
• Some examples would be test/changelogs, changelog, release_history, docs/changelog etc.
• By default it is changelogs folder

changelog_folder: "changelogs" 

changelog_version_prefix

under changelog folder, there are files like v0.1.0.md if the prefix is "V"

• As I've mentioned above, this is a rule for targeting only prefixed changelogs.
• If you have _2.4.3.md in there for some reason and other changelogs as v2.4.2.md, v2.4.3.md you could easily include only those two files by setting prefix to "v". It would only look for files that start with v and sort from those.

changelog_version_prefix: "" 

changelog_insert_before

I like my legal stuff at the bottom of the readme and release history before that

• Let's say you like sorting things a bit differently and think that Legal stuff should be at the bottom of your readme file. No worries! Just tell it to place changelogs before legal.md
• Important: The file you set must be in the order list in the task. Meaning that it should be something that is going to be included in the readme file. If there is no legal.md file that will be included in the generated readme, then it will put the changelog in the end of the file.
• This is separate than the order object you set for the task because changelog is automatically generated
• Examples for this can be any file from the order list. For this readme I could have chosen getting_started.md or usage.md as well... But it would have been very silly.
• Default is:

changelog_insert_before: "" 

banner

I like some ascii art on the top of the readme

• This is one of the visually enhancing features. You can supply a header for your readme files in text format.
• I usually add an ascii logo of my project name. But you can provide logos, or other texts that you want to display on the top of the readme.
• It should be the path of the file in respect to the readme folder.
• Examples: "test/banner.md", "my_header.md", "my_plain_header.txt"
• It accepts a string and default is:

banner: null 

has_travis

I use travis a lot and want to have the travis image generated on the top

• If you use travis, you can add the image of your master branch automatically generated with this option
• If you aren't generating title automatically then this has no purpose, because it is displayed near the title.
• This option is either on or off
• By default:

has_travis: on

github_username

this is mainly for travis link

• When you are using travis, your username may not be gotten from the package.json
• Who knows if your username is the same as the author name, and who is to say which author you are!
• Therefore, you supply it with your username to have it generate the link as user/repo
• By default it has my username:

github_username: "aponxi" 

generate_footer

generates automatic footer that tells the time it was generated using this task

• You may want to call it my watermark, and you don't have to have it there at all!
• Although it would make me happy to see it there :)
• This adds a small footnote saying that this readme was generated by this grunt task and when it was generated.
• Example can be found on the bottom of this file (assuming that you are reading from the generated readme file and not the options.md)
• It can be either on/off for CoffeeScript and true/false for Javascript
• By default:

generate_footer: on 

generate_title

generates automatic title from package name and description

• This option is related to all the travis options.
• If this option is off, then travis options are disregarded.
• This option gets the package name and the package description from the package_name and package_desc options if they are set. If they aren't, then it gets the package name and description from the package.json file. Then the package name and descriptions are added to the top of the readme file.
• Be warned that table of contents uses the package name anchor to go to the top. So, if you aren't going to use this feature then have a title with the package_name in the readme.
• If you aren't going to supply either name or description via options, then you should dd pkg configuration to your grunt.initConfig so that we can scavenge it from the package.json for you. To do so add this line under grunt.initConfig in your Gruntfile:

grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    //....

• It can be either on/off for CoffeeScript and true/false for Javascript
• By default:

generate_title: on 

package_name

by default we get it from the package.json

• Back to top links from Table of Contents uses this to generate anchors that link to the title, thus allowing to jump to the top of the page.
• Generate title also uses this to generate the title
• This option accepts a string such as "My Plugin Title"
• By default it is empty, allowing the pacakge name to be gotten from package.json. To have it get it from package.json you must add this line under grunt.initConfig in your Gruntfile:

grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    //....

• Default value:

package_name : "" 

package_desc

by default we get it from package.json

• Generate title uses this to generate the title
• This option accepts a string such as "My Plugin Description"
• Feel free to use any markdown formats. However, it will be added as a quote with > in the beginning of the description.
• By default it is empty, allowing the package description to be gotten from package.json. To have it get it from package.json you must add this line under grunt.initConfig in your Gruntfile:

grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    //....

• Default value:

package_desc : "" 

informative

tell the people what's going on (verbose)

• This is somewhat for verbose outputs
• Informs what the task is doing
• It can be either on/off, yes/no for CoffeeScript and true/false for Javascript
• By default:

informative : yes 

• Example output:

>> Generating banner...
>> Writing package name and description...
>> Engineering travis button...
>> Generating table of contents...
>> Adding the generation message, thank you...
Your readme file "test/readme_no_changelog.md" is ready!

Release History

[Back To Top]

You can find all the changelogs here.

Latest changelog is for v0.2.0.md:

v0.2.0 05/Jun/2013

• Wrote the documentation
• Fixed some more issues with prefix check. Now if there isn't a prefix, it sorts the files under changelog alphabetically. z0.1.0.md, and v0.1.0.md are both included in the sorting process.
• changed some default options to more convenient values

Legal Mambo Jambo

[Back To Top]

Copyright © 2013 aponxi [email protected]

This software is licensed under MIT License.

This readme has been automatically generated by readme generator on Wed Jun 05 2013 20:35:51 GMT-0400 (EDT).