Nowadays using version control systems like Github or Bitbucket for our projects is pretty popular because of their flexibility.

When we are starting our projects both systems recommends the creation of a README.md file to provide an introduction to our projects, but it could turn into documentation.

At the first moment, the MD extension was not familiar to us, and it’s normal. The MD extension stands for MarkDown which is a series of dialing rules that will generate an HTML without knowing HTML for tags like bold, subtitle and other special labels in a similar way to that done by http://wikipedia.org.

If you want to know a little more about MarkDown, you can check the version of Github at https://help.github.com/articles/github-flavored-markdown and BitBucket version at https://bitbucket.org/tutorials/markdowndemo.

When we have mastered the MarkDown creating sections within our document, the natural evolution is to make a table of contents to make it easier to navigate through Readme file doing our project more professional, but this task can be cumbersome luckily we will see below a tool that does this job for us.

Install DocToc

Assuming you have Node.js installed in your system and therefore the npm command is available to run the following command to install the DocToc project.

$ npm install -g doctoc

Generating TOC

Once installed we just need to indicate on which files we are going to generate the TOC. If our project is in GitHub only must execute the following command

$ doctoc README.md

If our project is hosted in Bitbucket, we need to execute the command with a slight variation as shown below.

$ doctoc README.md --bitbucket

You can see a TOC generated by this command in the project https://github.com/enzolutions/community-bookstore/

I hope you have been to his liking.