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: https://github.com/isaacs/github/issues/215#issuecomment-807688648 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: https://github.com/github/markup/issues/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

[4F2E4A2E]

+1

[AzizSaleh]

+1

[nyh]

+1

[AshCoolman]

+1

[art-divin]

+1

[OpenESignForms]

+1 for an auto-generated TOC. All of my wikis ported from google code are much less useful with the TOC, but manually building them is a huge effort and will be error prone to say the least.

[lebolo]

:+1:

[cederom]

still no [TOC] ? even sourceforce has it! :-) +1

[dscho]

OMG if the GitHub people are as annoyed as I am by all those +1 mails spamming the inbox, this feature is never going to happen... :grinning:

[dreamcat4]

On Mon, Apr 13, 2015 at 10:13 AM, dscho notifications@github.com wrote:

OMG if the GitHub people are as annoyed as I am by all those +1 mails spamming the inbox, this feature is never going to happen... [image: :grinning:]

+1

— Reply to this email directly or view it on GitHub https://github.com/isaacs/github/issues/215#issuecomment-92283409.

[dscho]

@dreamcat4 LOL!

[p8952]

+1

[AndyWendt]

@dscho and @dreamcat4 here's another :+1: :smile: that made me laugh

[robbyoconnor]

:+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1: :+1:

[ogradyjd]

I just ran into this and behold, a feature request with never-ending +1s. Are the devs trying to tell us that ASCIIdoc is the way to go?

Also:

+!

[dscho]

I just ran into this and behold, a feature request with never-ending +1s. Are the devs trying to tell us that ASCIIdoc is the way to go?

Yeah, those +1s really hide the important comments, don't they? In particular, you could work around it locally by installing GreaseMonkey script, as I described above -- this works in Chrome and in Firefox, even on Android.

Also:

+!

Hahaha! You caps-locked the "1"... :grinning:

[AndyWendt]

+! > +1 :smile:

[ada-lovecraft]

Excuse me, but can I sit on your keyboard? :cat2:

+1

[eterps]

:+1:

[JamesLavin]

Everyone's sick of all the +1s on this thread, so I'm issuing a joint +2 with my colleague Pinny.

[Franck-Dernoncourt]

:+1: I tried to generate the table of contents with pandoc, but so far I have only managed to generate TOCs without any links. Any idea is welcome!

[kdemarest]

+1

[einverne]

+1

[robbyoconnor]

FYI you can use emacs to generate a toc but something like this in the Web UI would be nice. Similar for vim likely. Works adequately for me.

On 05/12/2015 08:24 AM, Ein Verne wrote:

+1

— Reply to this email directly or view it on GitHub https://github.com/isaacs/github/issues/215#issuecomment-101257329.

[svoop]

+1

[bkuberek]

:+1:

[theofidry]

+1

[jayschwa]

+1

[brokenalarms]

:+1:

[nelson6e65]

:+1:

[ikitommi]

:+1:

[ryanhoo]

If you want to make a sense of the structure of whole article, you really need a nice fixed table of contents on either the left/right or top of the page.

[davelnewton]

:+1: although in theory I should be rolled into JamesLavin's +2, making it a +3, and eliminating the need for this :+1:.

[shadowbq]

+1 please.

[alejdg]

+1

[archiecobbs]

+1

[Delawen]

Probably, after a year ignoring this, it won't be done. But :+1:

[adamwdennis]

+1

[sebask]

+1

[amaiorano]

I wrote a python script to generate a TOC from a markdown file: https://github.com/amaiorano/md-to-toc

This will work on any markdown file - doesn't need to be on a public GitHub repo.

[arrowplum]

@sebask had a lot of good things to say. I will just add my own two cents:

+1

[toshimaru]

++1

[likejazz]

+1

[isogram]

+1

[cornelone]

+1

[cyChop]

+1

[AndyWendt]

:+1:

[ricardoamaro]

+1

[posix4e]

+1!

[kdemarest]

I looked into creating a web service that would read the .md file, generate the TOC and return appropriate insertable content, but of course the markdown is too locked down for that.

However, I did find the location of the code. Perhaps someone will beat me to the punch creating a PR for this:

https://github.com/github/markup