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

[RuedigerMoeller]

+5

[AndyWendt]

+99

[leissa]

My current workaround:

#!/bin/sh
#
# A pre-commit hook to automatically generate a table of contents on top of each *.md file.
# you need doctoc for this hook to work:
# https://github.com/thlorenz/doctoc

doctoc --title "**Contents**" --github .

put this in .git/hooks/pre-commit

see, e.g., here: https://github.com/AnyDSL/anydsl/wiki/Programming-Guide

[maxless]

Well, a year has passed...

[Kobold]

+1

[benhourigan]

+1

[shreyansb]

+1!!!

[AndyWendt]

:+1: +1 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

[ObjectiveTruth]

:+1:

[saurabh-agrawal83]

+1

[atesgoral]

:+1:

[leafpeak]

ETA????!!!

[blakehawkins]

:+1:

[aldanor]

!

[jwaldrip]

+1

[TWiStErRob]

+1

[reckart]

+1

[brunobowden]

Can we have a more meaningful update on this bug? Ideally a statement from GitHub about whether they'll be working on this and if so, then over what time frame.

I think it would be better to lock down the bug as the numerous +1's are noisy rather than helpful. You can still lend your weight in support by subscribing to the bug. The other comments with more detail have been helpful.

[shadowbq]

Hi shadowbq,

Thanks for writing in, and sorry for the frustration. As the user 'isaacs' states in his repo's readme, the issues listed there are not official GitHub issues or WIP items. We have had several users request this feature, and we'll add your +1 to this request, but we can't say if/when the feature will be implemented since our product roadmap is determined by a large number of factors. The team will definitely read through your concerns though, so thanks again for your email.

Cheers, The GitHub Support Team

[ourmaninamsterdam]

:+1: :+1:

[gawen]

:+1:

[tolgaek]

:+1:

[PiotrJustyna]

:+1:

[304NotModified]

+1

[florianajir]

+1

[hohwille]

It used to work fine with asciidoc using

:toc:
toc::[]

However this stopped to work recently. :-1:

[pando85]

+1

[brunobowden]

You can generate a TOC for a markdown page, by opening the javascript console on the public page and then running the following script. It will output the links that you can then enter in to your document. You may need to adjust the 'article>h3' setting depending on your hierarchy. It would of course be much better if this was generated automatically or before commits.

$('article>h3').map(function(i){ var txt = $(this).text(); var href= $(this).find('a').attr('href'); return "- [" + txt + "](" + href + "%29"; }).get().join('\n');

[304NotModified]

@brunobowden good idea.

It's not fully working. Maybe post it with fenced code blocks?

[brunobowden]

Thansks @304NotModified - I should know better to do that. This works on a public page but it would be helpful to adapt it to run on preview pages as well, so you can do the update from a PR before it's merged.

$('article>h3').map(function(i){
    var txt = $(this).text();
    var href= $(this).find('a').attr('href');
    return "- [" + txt + "](" + href + ")";
}).get().join('\n');

[originalfoo]

I prefer pages that are impossible to navigate, especially when trying to learn how to use a new code library, it makes finding information so much harder and delightfully tedious. /sarcasm

It's somewhat bemusing that GFM can't even muster a table of contents. Makes me wonder if markdown is the right tool for the job?

[stereobooster]

https://github.com/gollum/gollum/wiki#table-of-contents-toc-tag

[brunobowden]

Gollum only works on the Wiki and not on the markdown files in the main repo.

On Mon, Aug 31, 2015 at 9:35 AM stereobooster notifications@github.com wrote:

https://github.com/gollum/gollum/wiki#table-of-contents-toc-tag

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

[flyhigher139]

+1

[GrahamTheCoder]

:+1:

[aioue]

+1

[altsheets]

[[toc]] please

[bbozo]

[[toc]] for world peace :+1:

[perryism]

:+1:

[304NotModified]

PS

Post an issue if you have an issue or feature request for GitHub. But you should also email support@github.com, since this repo is strictly for our own (unofficial) tracking purposes

[stresslimit]

+1 we've moved to .adoc to get this, but it's annoying compared to a lot of GFMD features.

[wbharding]

140 developers and counting, github. +1 Doesn't seem like rocket science here.

[altsheets]

On 17 September 2015 at 06:10, GitHub Staff support@github.com wrote:

[[toc]] please

Thanks for the suggestion, we'll definitely pass that on to the team to consider. Let us know if there's anything else we can help you with!

Cheers, GitHub Support

[ake-persson]

+1

[zfedoran]

+1

[pbrit]

+1

[zackhsi]

+1

[Sebb767]

+1

[ghost]

+1

[agrbin]

+1