This tiny tutorial shows, how to generate a TOC for Markdown with the help of a tiny npm package called doctoc in just a few seconds.

Since a while I write down the most important facts about a project or an module to the README.md file of the corresponding GIT repository. That’s good to  keep the documentation as close to the code as possible and to minimise the rampup time for my developers. The problem for me was , that it took me a lot of time to produce a table of contents on top of the document. But now I found a really good npm package, that manages that really quickly.  And it supports the most important Markdown dialects or formats which are used by Bitbucket, GitLab or GitHub. This is how to generate a TOC for Markdown.

Generate a TOC for Markdown

1. install npm package doctoc:
   $> npm install -g doctoc # maybe as sudo
2. cd  into folder where your README.md is situated
3. place markers in your README.-md to define, where the table of content should be placed:

   ### Markdown
   Some text stuff gedöhns
   ...
   
   <!-- START doctoc -->
   <!-- END doctoc -->
   
   ...
   Other Markdown stuff ...

   If you skip this step, the TOC is placed in the very beginning of the document.

4. run on of the following doctoc commands depending on your target platform:

   $> doctoc README.md --bitbucket # for Bitbucket format
   $> doctoc README.md --github    # for github.com format
   $> doctoc README.md --gitlab    # for gitlab.com format
   

5. For Bitbucket I had to remove the HTML-comments generated by doctoc afterwards, because they where rendered on the project landingpage
6. That’s how to generate a TOC for Markdown. The generated Markdown shout be placed between <!– START doctoc –>  and <!– END doctoc –>

Further information on generate a TOC for Markdown

• official doctoc npm package page: https://www.npmjs.com/package/doctoc
• Markdown on WikiPedia: https://en.wikipedia.org/wiki/Markdown
• Markdown Cheat-Sheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
• Markdown Bitbucket: https://bitbucket.org/tutorials/markdowndemo
• Bitbucket Comments Bug (I think its a bug): https://bitbucket.org/tutorials/markdowndemo/issues/15/how-can-you-insert-comments-in-the