Table of Contents
jehna opened this issue · 1 comments
jehna commented
From proposal of @lehtu:
[ToC] would be nice to have, especially when you have a long README
jehna commented
There has been conversation about bringing automatic ToCs to Github Flavoured Markdown:
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.