- next level braining -

Generate a TOC for Markdown (Bitbucket, Git or Gitlab)

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

install npm package doctoc:$>npm install-gdoctoc# maybe as sudo

cd into folder where your README.md is situated

place markers in your README.-md to define, where the table of content should be placed:

MATLAB

1

2

3

4

5

6

7

8

9

###Markdown

Some text stuff gedöhns

...

<!--START doctoc-->

<!--ENDdoctoc-->

...

Other Markdown stuff...

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

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

Shell

1

2

3

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

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

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

For Bitbucket I had to remove the HTML-comments generated by doctoc afterwards, because they where rendered on the project landingpage

That’s how to generate a TOC for Markdown. The generated Markdown shout be placed between
<!--START doctoc--> and
<!--ENDdoctoc-->