Automatic TOC in github-flavoured-markdown

Question

I created two options to generate a toc for github-flavored-markdown:

DocToc Command Line Tool (source) requires node.js

Installation:

npm install -g doctoc

Usage:

doctoc . to add table of contents to all markdown files in the current and all sub directories.

DocToc WebApp

If you want to try it online first, go to the doctoc site, paste the link of the markdown page and it will generate a table of content that you can insert at the top of your markdown file.

Github Wikis and Anchors

As Matthew Flaschen pointed out in the comments below, for its wiki pages GitHub previously didn't generate the anchors that doctoc depends on.

UPDATE: However, they fixed this issue.

GitHub Pages (which is basically a wrapper for Jekyll) appears to use kramdown, which implements all of Maruku, and therefore has support for an automatically generated table of contents via atoc attribute:

* auto-gen TOC:
{:toc}

The first line just starts an unordered list and is actually thrown away.

This results in a nested set of unordered lists, using the headers in the document.

Note: this should work for GitHub Pages, not GitHub Flavored Markdown (GFM) as used in comments or wiki pages. AFAIK a solution doesn't exist for that.

If you edit Markdown files with Vim, you can try this plugin vim-markdown-toc.

The usage is simple, just move your cursor to the place you want to append Table of Contents and run :GenTocGFM, done!

Screenshots:

Features:

1. Generate toc for Markdown files. (Support GitHub Flavored Markdown and Redcarpet)

2. Update existing toc.

3. Auto update toc on save.

Update March 2021: GitHub added an official workaround

READMEs now show a ToC like this as you scroll down into them:

demo: https://github.com/cirosantilli/test-git-web-interface/tree/master/d

It does not render inside the document as I wanted for better Ctrl + F, but it is better than nothing.

Also also works for non-README as well now, e.g.: https://github.com/cirosantilli/test-git-web-interface/blob/master/md.md

They also added a repository setting to enable disable that. It's so weird, who would ever want to disable it? Under https://github.com/cirosantilli/test-git-web-interface/settings Features:

Table of contents

Autogenerate table of contents for Markdown files in this repository. The table of contents will be displayed near the top of the file.

Original answer

It's not possible, except for the workarounds proposed.

I proposed Kramdown TOC extension and other possibilities to [email protected] and Steven! Ragnarök replied with the usual:

Thanks for the suggestion and links. I'll add it to our internal feature request list for the team to see.

Let's upvote this question until it happens.

Another workaround is to use Asciidoc instead of Markdown, which does render TOCs. I've moved to this approach for my content nowadays.

It's not automatic, but it uses Notepad++ regular expressions:

Replace all first by the second (removes all lines not having headers)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

Then (converts headers III to spaces)

-##
        -

Then (converts headers II to spaces)

-#
    -

Then (remove unused chars at the beginning and at the end of link title)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

Then (convert last tokens lowercase and dash instead of spaces)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

Remove unused final pounds and initial dashes:

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

Remove useless chars in links:

(\].*?)(?:\(|\))
\1

And finally add parenthesis around final links:

\](?!\()(.*?)$
\]\(\1\)

And voilà! You can even put this in a global macro if you repeat it enough time.

Github Flavored Markdown uses RedCarpet as their Markdown engine. From the RedCarpet repo:

:with_toc_data - add HTML anchors to each header in the output HTML, to allow linking to each section.

It seems in that you'd need to get at the renderer level to set this flag, which isn't possible on Github obviously. However, the latest update to Github Pages, it seems that automatic anchoring is turned on for headers, creating linkable headings. Not exactly what you want, but it might help you create a TOC for your doc a bit easier (albeit manually).