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 first moment the MD extension were not familiar for us and it's normal. The MD extension stands for MarkDown which is a series of dialing rules that will generate a 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.
Assuming you have Node.js installed in your system and therefore the npm command is available run the following command to install the DocToc project.
$ npm install -g doctoc
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 just need 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.