Insert automatically generated table of contents TOC on rendered markdown files like README.md.

[cirosantilli]

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

[captn3m0]

You can automatically generate TOC via http://doctoc.herokuapp.com/. There is also an npm package available here to do it on the command line.

But yes, these are ultimately just manual methods because you need to manually copy and paste the TOC into the markdown. But one benefit of it is that the toc is maintained everwhere, even across apps that don't use GFM for rendering.

[cirosantilli]

I hope GitHub fix some standard extension syntax, possibly backing up Kramdown's, and potentially settle the existing extension mess with it's influence.

[ekalinin]

Here's my try to solve this issue without any addional software (on linux) — github-markdown-toc

[quasipedia]

👍

[ezequielgarcia]

+1

[robbyoconnor]

+1

[maxlinc]

Another workaround...

Although I'd like to see TOC support in GFM, if you want TOC's rendered by GitHub today than you could switch to asciidoc. Asciidoc has built-in support for TOC, and with the right options it will be rendered by GitHub.

I'm a fan of Markdown so I'm hesitant to asciidoc, but the article on Living the Future of Technical Writing by GitHub's @schacon, which talks about switching from Markdown to Asciidoc, has made willing to consider the jump. There's also several other features other features in asciidoc-samples - besides TOC - that don't seem to have working GFM equivalents. Footnotes, for example.

If you want give asciidoc a shot, you can use pandoc to convert your existing markdown:

pandoc -t asciidoc -f markdown README.md > README.asciidoc

[cirosantilli]

@maxlinc thanks a lot for the schacon link! I was really curious to why he used Asciidoc on Pro Git 2.

[quasipedia]

@maxlinc - I subscribe the thanksgiving by cirosantilli! 👍

[mikecharles]

@ekalinin I suppose this won't work for private repos?

[ekalinin]

@ekalinin I suppose this won't work for private repos?

@Mike-Charles yes, unfortunately github-markdown-toc won't work for private repos

[sv3ndk]

+1

[mockitoguy]

+1

[Manuzor]

+1