Automatic TOC in github-flavoured-markdown

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.

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.