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

grunt-readme-generator

A grunt task to generate a dynamic readme.md from partial markdown files in readme folder. Specifically designed for GitHub projects!

Jump to Section

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

Getting Started

[Back To Top]

This plugin is to generate readme files from many tiny sections of the readme. The readme you are reading is also generated with this plugin!

Lets say you have a readme structure such as:

- Installation
- Usage
    -- Example
    -- Example Output
- Documentation
    -- Options
        --- option1
        --- option2
    -- API
- License
- Contributing

• You can write a task to generate Options.md from option1.md and option2.md
• Then a task to generate Documentation.md from Options.md and API.md
• Another task to generate Usage.md from Example.md and Example Output.md files
• And wrap it all up by creating the Readme.md from Installation.md, Usage.md, Documentation.md, License.md and Contributing.md
• voilà !

Examples and tests

There are several readme files that were generated to test options. The grunt file has several tasks written to generate these readme files. The outputs of them can be found in the test folder. Here are quicklinks to those files:

• Default Options
• No Package Info
• All Options
• Different Header
• No Changelog
• No Footer
• No Table of Contents
• No Travis
• Testing for Abnormalities

Highlights

• Automatic table of contents generation
• Automatic Back To Top link generation
• Highly customizable for many many parts of the bigger picture
• Automatic Title and Description generation on the top
• Option to generate travis build status image on the top for desired branch
• Specifically designed for GitHub projects and GFM
• Optional banners on the top to put a logo or ascii art!

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]

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

grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  readme_generator: {
    my_generator : { //Thank you @JFusco
      options: {
        // Task-specific options go here.
        // detailed explanation is under options
        // Default options:
        readme_folder: "readme",
        output: "README.md",
        table_of_contents: true,
        toc_extra_links: [],
        generate_changelog: false,
        changelog_folder: "changelogs",
        changelog_version_prefix: null,
        changelog_insert_before: null,
        banner: null,
        has_travis: true,
        github_username: "aponxi",
        travis_branch: "master",
        generate_footer: true,
        generate_title: true,
        package_title: null,
        package_name: null,
        package_desc: null,
        informative: true,
        h1: "#",
        h2: "##",
        back_to_top_custom: null
      },
      order: {
        // Title of the piece and the File name goes here
        // "Filename" : "Title"
        "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: null 

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: null 

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" 

travis_branch

this specifies the travis branch that you want to use for the build status logo

• If you want to use develop branch for your travis build status logo then set it to "develop"

• This only works if you have generate_title and has_travis turned on

• By default:

travis_branch : "master"

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_title

This can be different than the package name, this will be on the title of the readme and used for anchor purposes to go back to the top

• This overrides package_name option for title.
• Allows you to customize your Readme title
• For example instead of grunt-readme-generator I could say Readme Generator

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.
• While generating the travis image, we use package name
• 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 : null 

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 : null 

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!

h1

for the auto generated title of the readme

• If you are generating a documentation from many different markdown files then you would probably want the big titles be ### option group and smaller titles be ### option and when you are generating the whole readme from another grunt task then you would want the title of the many option groups to be ##Options
• By setting this option to ### you can make the titles of the markdown files to be ### title
• Be sure to set h2 option to ### for that case, so that sub-titles will appear nicely.
• By default:

h1 : "#"

h2

for the auto generated title of the section, like usage or legal or installation parts of the readme

• Similar to the h1 option, set this to make the sub-titles appear differently
• Usually used with h1 option
• By default:

h2 : "##"

back_to_top_custom

where backtotop leads you, by default it takes you to the title of the readme

• This is used with table_of_contents option
• Normally, it would take you to the Table of Contents. This is to override that.
• If you want to change that for whatever reason, set it to the exact link you want to provide
• for example back_to_top_custom : "#my-custom-anchor-in-the-readme-page"
• By default:

back_to_top_custom : null

Release History

[Back To Top]

You can find all the changelogs here.

Latest changelog is from v0.3.0.md:

v0.3.4 23/Aug/2013

• added relative options to test readmes
• fixed doc

Legal Mambo Jambo

[Back To Top]

Copyright © 2013 aponxi aponxi@weaponxi.com

This software is licensed under MIT License.

---

This readme has been automatically generated by readme generator on Fri Aug 23 2013 20:55:02 GMT-0400 (EDT).