ENH: markdown: Table of Contents (with_toc_data)

[westurner]

• add a syntax directive for including a Table of Contents (TOC) in markdown documents

redcarpet now supports a with_toc_data (--render-with-toc-data) option for automatically generating a Table of Contents <ul> from markdown setext (=,_ underline) and ATX (# prefix) headings.

• with_toc_data: GitHub style anchors vmg/redcarpet#186 (comment) ("with_toc_data: GitHub style anchors ", Changelog entry)
• TOC links / permalink generation vmg/redcarpet#391 (comment) ("TOC links / permalink generation")
• Duplicate anchor names vmg/redcarpet#307 (appending incrementing numeric values for duplicate headers)
• Ampersand (&) not rendered correctly in Table Of Contents vmg/redcarpet#529 (ampersand & not rendering correctly)

[westurner]

Coming from ReStructuredText (docutils (setext)), auto-generated Table of Contents directives are a really useful feature.

.. ```restructuredtext

.. contents::

.. contents:: Table of Contents 2
   :depth: 10
   :local:

• http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
• http://docutils.sourceforge.net/COPYING.html (Public Domain (:+1:))

[tukkek]

I strongly second this: every major markup language for wikis has a table-of-contents feature. The sheer number of people who have created scripts, userscripts and online tools in this thread to help us do it manually goes to show how important such a feature is! Not to mention the almost 300 comments there - mostly "+1" comments as one is quick to notice.

There are several questions on Stack Overflow about this as well, not to mention other sites:

• http://stackoverflow.com/questions/9721944/automatic-toc-in-github-flavoured-markdown?s=1|0.0000
• http://stackoverflow.com/questions/9239588/toc-or-sidebar-in-github-wiki?s=3|0.0000

Sure GitHub offers other markup languages that have this feature but markdown is their default one by choice - there is no excuse for them not to go ahead and deal with this issue once and for all.

[tukkek]

I've just received a reply from GH on this. Spoiler alert: its pretty depressing, despite this issue already having over 40 thumbs up when I wrote to them.

If a GH staff member is reading this please forgive me but doesn't look like they care at all since they couldn't be bothered to even make a comment here or in the linked thread. As you can see from the other thread that is pretty much their default reply every time they're contacted so I'm really having a hard time believing something will be done about this in the next few years.

Thanks GH, up to now I had nothing but respect for this website.

Thanks for reaching out! We don't comment publicly on our roadmap, so I'm not able to say if or when this will happen, but I will definitely add your +1 to the feature on our internal feature request list.

Thanks again for reaching out and for using GitHub!

Regards,
GitHub Support

[tukkek]

EDIT: Now that I think of it there is zero evidence they even bothered to open up the link and see this issue. I've also cleaned up my last comment since it was badly written.

[abalter]

Make sure it's known that there are a zillion people here who want it.

isaacs/github#215

[franslundberg]

+1. Please, implement this crucial feature.

[brabenetz]

+1

[joihelgi]

+1

[steel]

+1

[jlengstorf]

Jekyll has support for a table of contents via Kramdown:

- 
{:toc}

NOTE: There's a space after that hyphen that's required for it to work properly.

It's not particularly flexible, but given that GitHub Pages is running Jekyll, it could be worthwhile to use this style of ToC generation — that way if I'm looking at the source for a GH Pages site, the ToC works on the live site and the Jekyll-generated site without issues.

Personally, I'd favor consistency over flexibility in this case. The lower learning curve for new users and decreased complexity to implement/maintain/support is a plus, too.

[i2000s]

I personally prefer to have a toggle content (toggle content under a title/header line) and/or table of contents switch on the top right corner of the Github markdown preview page. Currently, we have already had blame, history and source buttons on the top menu. Why not add another as/under a default preview options button defined by who created the doc and can be changed by readers?

The technical difficulty might be a burden on the server to generate previous pages case by case for different repos and/or for various readers. But I don't see why this cannot be done by GitHub staff.

@jlengstorf @westurner The problem of having an explicit {:toc} code line on the markdown doc is that the doc might be rendered using another markdown markup engine to generate a Github page or something else, and adding lines like {:toc} might bring in some conflicts or unexpected results on the resulted Github pages or other products.

I have also thought about enabling a global switch on one's github setting page, but the level of granular control of rendering seems too rough if one only wants to generate a table of contents or toggle all headers/titles on a few github pages. In the meantime, a reader can definitely have some level of control over what effect they want to see on markdown preview pages, but should the writer/owner of a doc have the control over the preview effect at the first place?

Just my 2cent. Of course, my 👍 to those who opens this issue and who contribute.

[jlengstorf]

I personally prefer to have a toggle content (toggle content under a title/header line) and/or table of contents switch on the top right corner of the Github markdown preview page.

@i2000s I'm not sure I follow what you're suggesting, but it seems it might be an entirely separate feature request.

The problem of having an explicit {:toc} code line on the markdown doc is that the doc might be rendered using another markdown markup engine

This is fair, but GitHub has already thrown in with Jekyll (and, by proxy, Kramdown) for GitHub Pages. It's the default there. What I'm suggesting is adding cross-channel support so that the GitHub default and the GitHub Pages default versions of Markdown files are consistent.

Anyone using alternative Markdown syntax is already generating their GH Pages files before sending up to GitHub, so this wouldn't break anything, and the lack of support for non-standard Markdown wouldn't change. Unless I'm missing something, this would be a non-breaking change that most people wouldn't notice — people using Jekyll would see improvements in the Markdown rendering on github.com, and that's all.

[kivikakk]

We're now using CommonMark, so feature requests of this sort should go to CommonMark Discussion or our support team if we were going to consider adding it to our own cmark implementation. Thanks!