Repository navigation
Insert automatically generated table of contents TOC on rendered markdown files like README.md. #215
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
Activity
[-]Allow to insert a table of contents TOC on rendered markdown files like README.md.[/-][+]Insert automatically generated table of contents TOC on rendered markdown files like README.md.[/+]captn3m0 commentedon Jun 22, 2014
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 commentedon Jun 22, 2014
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 commentedon Sep 2, 2014
Here's my try to solve this issue without any addional software (on linux) — github-markdown-toc
quasipedia commentedon Oct 22, 2014
👍
ezequielgarcia commentedon Dec 9, 2014
+1
robbyoconnor commentedon Dec 16, 2014
+1
maxlinc commentedon Dec 16, 2014
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:
cirosantilli commentedon Dec 16, 2014
@maxlinc thanks a lot for the schacon link! I was really curious to why he used Asciidoc on Pro Git 2.
quasipedia commentedon Dec 17, 2014
@maxlinc - I subscribe the thanksgiving by cirosantilli! 👍
mikecharles commentedon Dec 17, 2014
@ekalinin I suppose this won't work for private repos?
ekalinin commentedon Dec 18, 2014
@Mike-Charles yes, unfortunately github-markdown-toc won't work for private repos
sv3ndk commentedon Dec 28, 2014
+1
mockitoguy commentedon Jan 4, 2015
+1
Manuzor commentedon Jan 8, 2015
+1
428 remaining items
botatoes commentedon Apr 14, 2021
Here's the link to the changelog https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/ and docs update will come soon. This is now supported for all Markdown files (in the browser).
TPS commentedon Apr 14, 2021
@botatoes Thanks very much! Is there an ETA for TOC support in the GitHub mobile apps?
CatalanCabbage commentedon Apr 18, 2021
[[TOC]] *
@TPS
No, this shouldn't be closed! 😞
True, this is a nice feature.
But what we need is something like what GitLab supports - no-nonsense, just a Table of Contents on top.
Why?
Not obvious AT ALL, and does not seem like a part of the Markdown content.
A Table of Contents needs to be a part of the Markdown content, since it refers to the sections in the comment itself.
Image for reference:
There's NO WAY I could ever imagine that clicking that takes me to the ToC of the MD contents.
I first thought it would show a list of files on the same level for file navigation, and I've been using GitX for a long time.
But...
Why complicate this? I mean, it's cool and all, but why not just go with this, the
(and by all people I mean - even if Robinson Crusoe came back from 30 years on an island and saw this, he'd get it)
way?
Suggestion:
If you want to make the traditional ToC better, I would suggest that we implement something like Wikipedia's ToC with a hide/show option (but better looking). reference
We can choose to give a ToC using a
[[_TOC_]]or whatever, and then you can render it. Plus we can keep the cool button if you want. 😄Or maybe make it a really prominent collapsible sidebar, like we see in docs.
But TLDR is that as of now, that implementation does not warrant closing this issue.
xantari commentedon Apr 18, 2021
Still not seeing table of contents on Github Wiki pages :(
svoop commentedon Apr 18, 2021
@xantari Don't worry, it'll be there soon enough, give it another – say – 8 years. 😉
botatoes commentedon Apr 19, 2021
@CatalanCabbage The reason why we've picked the UI route first instead of injecting Markdown is because GitHub README.md files are rendered elsewhere outside of GitHub UI and injecting Markdown might create unexpected behaviors. That being said, we'll still be considering it for the future as a part of our improve GitHub Flavored Markdown effort.
@xantari I'm driving proposals for Wiki improvements right now and this is definitely on the list but no timeline yet 😅
CatalanCabbage commentedon Apr 19, 2021
@botatoes if that's the reason, then is it possible to
The problems with it now are that it's
Something like this (either on the left or right), prominent like you see in Docs when it's open?
Example from Jest:
hectoralicea commentedon Apr 29, 2021
I just got this working on GitLab via
[[_TOC_]]tag. Works great in my editor as well (using Typora). Very surprised GitHub does not support this simple feature.xantari commentedon Apr 29, 2021
@hectoralicea That’s also how Azure DevOps does it as well it’s so easy
mxmilkiib commentedon May 16, 2021
Wiki ToC issue is #504
Reorder the sections in the macros proposal.