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 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 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 --bitbucket # for Bitbucket format
    $> doctoc --github    # for format
    $> doctoc --gitlab    # for 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

Leave a Reply

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.