Description
Edit March 2021: GitHub now added a workaround mentioned at: #215 (comment) That is a good step, but I'll keep this open until they actually add a way to add it inside the rendered output (which can be e.g. searched more easily with Ctrl+F).
When I see a manually generated table of contents, it makes me sad.
When I see a huge README that is impossible to navigate without it, it makes me even sadder.
LaTeX has it. Gollum has it. Pandoc has it. So why not GFM?
There are some tools that automate the generation, but they're just an ugly hack:
- require a Make before pushes
- add output to version control
- modify our dear source code for us
Now the bitter part: what syntax to use?
Whatever is chosen, it should be a standard way to extend Markdown, so that other extensions can be added later on.
One possibility is to use Kramdown extension syntax and insert the TOC with {:toc max_level=3 }.
Redcarpet already has a command that generates the TOC: Redcarpet::Render::HTML_TOC, but no way to insert it, and no standard way to extend markdown.
Same for GitLab: http://feedback.gitlab.com/forums/176466-general/suggestions/5790538-extension-for-inserting-a-table-of-contents-toc
StackOverflow: 66 upvotes as of 2014-06: http://stackoverflow.com/questions/9721944/automatic-toc-in-github-flavoured-markdown
There is an issue for the library GitHub uses to render markdown at: github/markup#904
Steven! Ragnarök replied with the neutral:
Thanks for the suggestion and links. I'll add it to our internal feature request list for the team to see.
Asciidoc
I got tired of waiting and started using Asciidoc. I recommend it, the format is really good. Just look at the typographical beauty of this: https://github.com/cirosantilli/linux-kernel-module-cheat/blob/7d9102373d60bd159920abfe96d636420afedd67/README.adoc