Insert automatically generated table of contents TOC on rendered markdown files like README.md.
cirosantilli opened this issue · comments
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/************/linux-kernel-module-cheat/blob/7d9102373d60bd159920abfe96d636420afedd67/README.adoc
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.
I hope GitHub fix some standard extension syntax, possibly backing up Kramdown's, and potentially settle the existing extension mess with it's influence.
Here's my try to solve this issue without any addional software (on linux) — github-markdown-toc
👍
+1
+1
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
@maxlinc thanks a lot for the schacon link! I was really curious to why he used Asciidoc on Pro Git 2.
@ekalinin I suppose this won't work for private repos?
@ekalinin I suppose this won't work for private repos?
@Mike-Charles yes, unfortunately github-markdown-toc won't work for private repos
+1
+1
+1
+1
No offline approaches are preferred than the GH online dynamic generation of TOC, as all offline approaches will be a burden and hard to maintain the TOC correctly.
+1
Why does a solution have to extend markdown?
@ekalinin's code can already create a ToC markdown file, so GH could just generate a new ToC on every change to readme.md, and display that file on the project's homepage above the real readme.md. Everyone gets a ToC for free with their readme.md files (and presumably can opt-in/out if they wish) without changing a single line of code.
Why does a solution have to extend markdown?
@MikeyBurkman - It does not need to, but if it did it, it would become part of the specification, and all libraries that works against that specification would support it (e.g.: github-markdown preview of the readme file in your IDE/editor of choice).
Preview of the TOC is important: on large documents is easy to get the levels wrong, for example.
+1
+1
+1
@quasipedia Surely you aren't saying that the necessity of a preview tool is a good reason to change the MD spec! That's like saying that not having some MD tool installed on my computer means I can't edit MD. Github already have a MD preview tool... just extend it to also preview the TOC.
As for external tools: the script to generate TOC from MD is publicly available. They can integrate if and when they want, and that integration would not be much different than supporting another MD spec. Only now your tools have to adjust, not every single user.
@MikeyBurkman - Surely you aren't saying that improving on standards is bad! ;)
Seriously: I can't but repeat myself: the solution does not need to extentd MD. GitHub has a history of creating standards that are to all effects "forks" of previously existing ones (GFM, TOML...). Since GFM is already a different standard than MD, and since GitHub is its creator and maintainer, it wouldn't surprise me if they would implement the TOC as part if it...
...but if that doesn't happen, I am just fine! :)
+1
+1
Have tried MarkdownTOC for sublime text today. Which might have been a alternative but sadly it doesn't work nearly well enough. No links and seems broken as it doesn't parse my markdown headings correctly.
[EDIT] npm install -g doctor && doctoc . is good though not integrated into ST. Probably worth making a ST command entry for it.
FWIW, I made this. https://github.com/ajkochanowicz/Smooth-ToCer
Obviously, it won't work with github readme files, but for any other markdown content that needs a TOC and can run JS...
+1
+1
+1
+1
+1
+1
👍
Bump 👍
+1
Just going to repeat myself here, and say that github should adopt the doctoc tool for auto-generating TOCs in markdown files. It's the best one available out there.
@dreamcat4 ditto here
yas
+1
+1
+1
My colleague @schmiedc and I have created a GreaseMonkey script that installs a new TOC button left of the h1 button which uses the excellent markdown-js library to add/refresh a table of contents.
The advantage over solutions like doctoc is that it integrates into GitHub's wiki editor and does not need users to work on their command-line (and require users to install tools like node.js). In Chrome, it works by drag 'n dropping into the Extensions page, in Firefox you will need to install the GreaseMonkey extension.
It will work with plain markdown (i.e. it does not handle code blocks correctly, as that is a GitHub extension to markdown). Contributions welcome.
@bumbu we specifically designed it to trigger only when the user edits wiki pages. But it should be really trivial to adjust by appending appropriate @include lines and extending this regular expression to accept more URLs than the "edit wiki page" ones.
Why not give it a shot yourself? As I mentioned, contributions are warmly welcomed.
+1
+1
+1
+1
@ekalinin I suppose this won't work for private repos?
@Mike-Charles yes, unfortunately github-markdown-toc won't work for private repos
@Mike-Charles just added an ability to work with local markdown files. So seems it may work with private repos.
@ekalinin thanks!
+1
+1
+1
+1
+1
+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.
👍
still no [TOC] ? even sourceforce has it! :-) +1
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... 😀
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:
😀]+1
—
Reply to this email directly or view it on GitHub
#215 (comment).
@dreamcat4 LOL!
+1
@dscho and @dreamcat4 here's another 👍 😄 that made me laugh
👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍 👍
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:
+!
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"... 😀
+! > +1 😄
Excuse me, but can I sit on your keyboard? 🐈
+1
👍
Everyone's sick of all the +1s on this thread, so I'm issuing a joint +2 with my colleague Pinny.
👍 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!
+1
+1
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
#215 (comment).
+1
👍
+1
+1
👍
👍
👍
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.
👍 although in theory I should be rolled into JamesLavin's +2, making it a +3, and eliminating the need for this 👍.
+1 please.
+1
+1
Probably, after a year ignoring this, it won't be done. But 👍
+1
+1
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.
++1
+1
+1
+1
+1
👍
+1
+1!
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