Reading large README.md files can be somewhat monotonous at best. When said READMEs do not have a table of contents, it can be even more tedious.

I recently discovered markdown-toc, a command line tool which will look after your table of contents for you.

You can install markdown-toc with:

npm install -g markdown-toc

markdown-toc will parse your markdown file and return the table of contents into the terminal.

markdown-toc README.md

This would still require for you to copy pasta the table of contents into your markdown file. markdown-toc can even inject/replace your table of contents directly in the file with the -i flag.

In order for this to work, you need to incude <!– toc –> and <!– tocstop –> placeholders in youe markdown file

<!-- toc -->

<!-- tocstop -->

# Getting started
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tempor elit sapien, 
eget fringilla metus faucibus congue. Curabitur nisl neque, lobortis sit amet du
i ac, euismod sagittis arcu. Donec felis velit, ultrices a nibh nec, lacinia fer
mentum erat. Duis nec orci id purus eleifend suscipit in nec nulla. Quisque vita
e tellus non lectus faucibus tincidunt. Curabitur convallis, dui eu auctor facil
isis, sem orci pellentesque nisi, nec pharetra libero dui sed ante. Maecenas ves
tibulum odio at sapien elementum varius. Nunc blandit vestibulum velit sit amet 
rutrum. Sed sodales ex diam, eget iaculis lorem ultrices a. Vivamus auctor quis 
felis et hendrerit. Integer ornare, leo id aliquet porta, tortor velit aliquam l
ibero, a finibus tortor turpis et orci.

# More Information
Pellentesque libero urna, tincidunt at augue sed, dictum cursus dolor. Duis sit 
amet lectus rutrum, elementum neque ac, faucibus nibh. Praesent eget eros imperd
iet, feugiat nibh nec, auctor justo. Sed efficitur faucibus elit, sed porttitor 
sem pharetra eu. Aenean pharetra mauris non lorem vulputate tristique. Maecenas 
maximus metus nec eros lobortis, dapibus auctor arcu pulvinar. Duis condimentum 
auctor vestibulum. Donec dictum semper neque, ut ultrices tellus laoreet a. Vest
ibulum eleifend eu metus ac tincidunt.

# Even More Information
Cras consectetur posuere ultricies. Suspendisse semper finibus massa at tincidun
t. Ut congue sapien sit amet felis facilisis porttitor. Vestibulum dictum eget l
acus in malesuada. Vivamus id nisl at metus faucibus sollicitudin. Aenean eget a
liquam risus, in accumsan nibh. Maecenas nisl ante, tincidunt in gravida in, tin
cidunt ut nisl. Donec lobortis sem quam, a maximus urna aliquam vel. Phasellus c
ongue lacus at tellus scelerisque, vel luctus erat finibus. Mauris consectetur u
t metus eget vehicula. Aliquam volutpat scelerisque mauris vitae rutrum. Maecena
s et mi eget lacus aliquam vulputate. Pellentesque ac pharetra ante, quis pulvin
ar libero. Aliquam quis tellus quis metus suscipit bibendum. Nulla pretium, tort
or eget tempor porttitor, sem risus blandit est, vitae ullamcorper odio eros vel
 arcu.

Then execute the command with the -i flag.

markdown-toc -i README.md

The logic here is a little odd. If you get your markdown file as output, then the placeholders haven’t been set correctly. If however you don’t get any output, then everything has gone through. Check your markdown file – mine now looks like this:

<!-- toc -->

- [Getting started](#getting-started)
- [More Information](#more-information)
- [Even More Information](#even-more-information)

<!-- tocstop -->

# Getting started
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tempor elit sapien, 
eget fringilla metus faucibus congue. Curabitur nisl neque, lobortis sit amet du
i ac, euismod sagittis arcu. Donec felis velit, ultrices a nibh nec, lacinia fer
mentum erat. Duis nec orci id purus eleifend suscipit in nec nulla. Quisque vita
e tellus non lectus faucibus tincidunt. Curabitur convallis, dui eu auctor facil
isis, sem orci pellentesque nisi, nec pharetra libero dui sed ante. Maecenas ves
tibulum odio at sapien elementum varius. Nunc blandit vestibulum velit sit amet 
rutrum. Sed sodales ex diam, eget iaculis lorem ultrices a. Vivamus auctor quis 
felis et hendrerit. Integer ornare, leo id aliquet porta, tortor velit aliquam l
ibero, a finibus tortor turpis et orci.

# More Information
Pellentesque libero urna, tincidunt at augue sed, dictum cursus dolor. Duis sit 
amet lectus rutrum, elementum neque ac, faucibus nibh. Praesent eget eros imperd
iet, feugiat nibh nec, auctor justo. Sed efficitur faucibus elit, sed porttitor 
sem pharetra eu. Aenean pharetra mauris non lorem vulputate tristique. Maecenas 
maximus metus nec eros lobortis, dapibus auctor arcu pulvinar. Duis condimentum 
auctor vestibulum. Donec dictum semper neque, ut ultrices tellus laoreet a. Vest
ibulum eleifend eu metus ac tincidunt.

# Even More Information
Cras consectetur posuere ultricies. Suspendisse semper finibus massa at tincidun
t. Ut congue sapien sit amet felis facilisis porttitor. Vestibulum dictum eget l
acus in malesuada. Vivamus id nisl at metus faucibus sollicitudin. Aenean eget a
liquam risus, in accumsan nibh. Maecenas nisl ante, tincidunt in gravida in, tin
cidunt ut nisl. Donec lobortis sem quam, a maximus urna aliquam vel. Phasellus c
ongue lacus at tellus scelerisque, vel luctus erat finibus. Mauris consectetur u
t metus eget vehicula. Aliquam volutpat scelerisque mauris vitae rutrum. Maecena
s et mi eget lacus aliquam vulputate. Pellentesque ac pharetra ante, quis pulvin
ar libero. Aliquam quis tellus quis metus suscipit bibendum. Nulla pretium, tort
or eget tempor porttitor, sem risus blandit est, vitae ullamcorper odio eros vel
 arcu.

But this still means, that I would have to remember to execute this command every time I make a change to the README.md file. What if there were a way to automate this too?

Simply setup a pre-commit GitHook to check for changes and update the table of contents for me.

Here’s one I like to use:

#!/bin/bash

GIT_ROOT_DIR="$(cd "$GIT_DIR/../"; pwd)"

# colour pallet
GREEN='\033[0;32m'
RED='\033[0;31m'
NC='\033[0m' # No Color



# Populate Table of Contents in README.md
CHANGED=`git diff HEAD --stat -- $GIT_ROOT_DIR/README.md | wc -l`

if [ $CHANGED -gt 0 ];
then
        echo -e "${GREEN}Changes have been detected in ${RED} $GIT_ROOT_DIR/README.md"
        markdown-toc -i $GIT_ROOT_DIR/README.md && echo -e "${GREEN}Updated Table of Contents in ${RED}$GIT_ROOT_DIR/README.md${NC}"
fi

Leave a Reply

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