Table of Contents

[Jesse Luoto]

From proposal of @lehtu:

[ToC] would be nice to have, especially when you have a long README

[Jesse Luoto]

There has been conversation about bringing automatic ToCs to Github Flavoured Markdown:

isaacs/github#215

The thread also has some nice tools that users have made to automatically generate ToCs.

I see a couple of issues regarding to hand-crafted ToCs:

• If ToC is something you'd need to update yourself, you probably won't do it
• The ToC should be the first thing of the README for the reader, but it should be the last one for the creator
• Creating ToC is not a creative, but rather mundane task that should be performed by an automated machine

A good ToC should be generated automatically by postprocessor of some kind:

• Github itself
• Your text editor (like in MSWord/Pages)
• Some CI tool
• A client-side JS when viewing the github page
• A client-side browser plugin

Moreover, you should keep your README.md file as compact as possible. If you feel like you'd need a ToC because of the length of your README, the best practice would be to break it to multiple smaller files, so the actual README would serve as a brief summary of the project with links to in-depth files like:

• CONTRIBUTING.md
• INSTALLING.md
• etc.