Skip to content
This repository has been archived by the owner on Nov 18, 2021. It is now read-only.

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

Closed
cirosantilli opened this issue Jun 21, 2014 · 428 comments

Comments

@cirosantilli
Copy link
Collaborator

cirosantilli commented Jun 21, 2014

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

@cirosantilli cirosantilli changed the title 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. Jun 21, 2014
@captn3m0
Copy link

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
Copy link
Collaborator Author

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
Copy link

ekalinin commented Sep 2, 2014

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

@quasipedia
Copy link

👍

2 similar comments
@ezequielgarcia
Copy link

+1

@robbyoconnor
Copy link

+1

@maxlinc
Copy link

maxlinc commented 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:

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

@cirosantilli
Copy link
Collaborator Author

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

@quasipedia
Copy link

@maxlinc - I subscribe the thanksgiving by cirosantilli! 👍

@mikecharles
Copy link

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

@ekalinin
Copy link

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

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

@sv3ndk
Copy link

sv3ndk commented Dec 28, 2014

+1

2 similar comments
@mockitoguy
Copy link

+1

@Manuzor
Copy link

Manuzor commented Jan 8, 2015

+1

@joeyu
Copy link

joeyu commented Jan 9, 2015

+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.

@ErikMHummel
Copy link

+1

@MikeyBurkman
Copy link

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.

@quasipedia
Copy link

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.

@guillaume-alvarez
Copy link

+1

2 similar comments
@jon-hanson
Copy link

+1

@eidng8
Copy link

eidng8 commented Jan 19, 2015

+1

@MikeyBurkman
Copy link

@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.

@quasipedia
Copy link

@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! :)

@adamjgrant
Copy link

+1

@dreamcat4
Copy link

+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.

@adamjgrant
Copy link

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...

@bumbu
Copy link

bumbu commented Feb 11, 2015

+1

2 similar comments
@robsterlini
Copy link

+1

@martinheidegger
Copy link

+1

@albertkun
Copy link

albertkun commented Mar 31, 2021

@botatoes this is such a great feature!!! I am using GitHub to teach a class and am very happy about the TOC!

One request, is it possible to have an option in the repo for it to be "expanded on default" and have it on the right side so it doesn't cover the headers?

something like this would be ideal:
image

regardless, thank you for this amazing feature!!

@captn3m0
Copy link

captn3m0 commented Apr 4, 2021

Minor concerns with the new feature:

  1. The new feature only works on the website, not on the Mobile App (I tested on iOS, might be supported on Android).
  2. It also feels very non-obvious (unless I was looking for it, I'd never have clicked it). Especially for projects on GitHub that don't have developers (regular GitHub users) as the primary audience (stuff like https://github.com/adamdriscoll/awesome-covid19-resources for eg).

@albertkun
Copy link

albertkun commented Apr 4, 2021

@botatoes Thanks also for implementing this for the mobile site. Any word when it'll be on the mobile apps?

@TPS It works great on Firefox Android web browser.

@SiddharthShyniben
Copy link

SiddharthShyniben commented Apr 5, 2021

@captn3m0 It doesn't appear on Android too. And also it works on Chrome Android

@botatoes
Copy link

botatoes commented Apr 5, 2021

@captn3m0 Our web implementations is the most to date. The mobile app team has their own backlog which means features aren't always aligned to ship at the same time. TOC should work on web mobile view though. Let me know if that's not the case for you.

@thorade
Copy link

thorade commented Apr 8, 2021

Seems this feature was announced here:
https://twitter.com/github/status/1376636651963842562
Is there any documentation elsewhere?

@botatoes
Copy link

botatoes commented Apr 8, 2021

@thorade there will be a changelog and updated docs. I'm just waiting for the additional non-README Markdown support coming either late this week or early next week before I push out the docs.

@botatoes
Copy link

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 TPS added implemented and removed WIP labels Apr 14, 2021
@TPS TPS closed this as completed Apr 14, 2021
@TPS
Copy link
Collaborator

TPS commented Apr 14, 2021

@botatoes Thanks very much! Is there an ETA for TOC support in the GitHub mobile apps?

@TPS TPS unpinned this issue Apr 14, 2021
@CatalanCabbage
Copy link

CatalanCabbage commented 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

  • the simple,
  • more effective,
  • flexible (I can choose not to give a ToC),
  • more obvious (if it's on top and a part of the MD file, it's the ToC of the MD file, duh),
  • more easy to use by literally all people (that's the global format, intuitive)
    (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.


  • I have a dream! That one day when ToC is implemented better, this will be rendered as a proper ToC

@xantari
Copy link

xantari commented Apr 18, 2021

Still not seeing table of contents on Github Wiki pages :(

@svoop
Copy link

svoop commented Apr 18, 2021

@xantari Don't worry, it'll be there soon enough, give it another – say – 8 years. 😉

@botatoes
Copy link

@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
Copy link

@botatoes if that's the reason, then is it possible to

  • Make it really noticeable so that it's intuitive for non-devs
  • Allow authors to enable or disable it somehow

The problems with it now are that it's

  • Hard to find
  • Hides content when it's open, so you cannot read the file while keeping this open

Something like this (either on the left or right), prominent like you see in Docs when it's open?

Example from Jest:
image

@hectoralicea
Copy link

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
Copy link

xantari commented Apr 29, 2021

@hectoralicea That’s also how Azure DevOps does it as well it’s so easy

@mxmilkiib
Copy link

Wiki ToC issue is #504

munificent added a commit to dart-lang/language that referenced this issue Oct 8, 2021
Because the diff of this is a nightmare, I have made no substantial
changes. All I did was reorganize the existing sections and add some
TODOs for parts to fill in. This means the resulting prose doesn't
flow and is weird in some places. I'll fix that in follow up PRs, but
I wanted to do the reordering separately since the diff is unreadable.

I also removed the TOC from the top since GitHub generates one
automatically: isaacs/github#215 (comment)
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests