Automatic TOC in github-flavoured-markdown

Question

Is it possible to generate an automatic Table of Contents using Github Flavoured Markdown?

Answer 1

Currently it's not possible using markdown syntax (see the ongoing discussion at GitHub), however you can use some external tools such as:

• Online Table Of Content Generator (raychenon/play-table-of-contents)
• arthurhammer/github-toc - browser extension that adds a table of contents to GitHub repos

---

Alternatively use AsciiDoc instead (e.g. README.adoc), e.g.

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

as suggested in this comment. Check the demo here.

Answer 2

It is possible to generate a webpage automatically with http://documentup.com/ from the README.md file. It's not creating a TOC, but for many it might solve the reason for wanting to create a TOC.

Another alternative to Documentup is Flatdoc: http://ricostacruz.com/flatdoc/

Answer 3

Use coryfklein/doctoc, a fork of thlorenz/doctoc that does not add "generated with DocToc" to every table of contents.

npm install -g coryfklein/doctoc

Answer 4

For Github's Texteditor Atom check out this awesome plugin (or "package" in Atom-lingo), which generates "TOC (table of contents) of headlines from parsed markdown" files:

markdown-toc

Once installed as Atom-package you can use the shortcut ctrl-alt-c to insert a TOC based on your markdown-doc-structure at the current cursor position...

Screenshots:

Atom Keybindings

markdown-toc gives you the following default key-bindings to control the plugin in Atom:

• ctrl-alt-c => create TOC at cursor position
• ctrl-alt-u => update TOC
• ctrl-alt-r => delete TOC

Plugin Features (from the project's README)

• Auto linking via anchor tags, e.g. # A 1 → #a-1
• Depth control [1-6] with depthFrom:1 and depthTo:6
• Enable or disable links with withLinks:1
• Refresh list on save with updateOnSave:1
• Use ordered list (1. ..., 2. ...) with orderedList:0

Answer 5

There's now a GitHub Action accomplishing this:

https://github.com/marketplace/actions/toc-generator

1. Specify location of TOC (option) e.g. README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Setup workflow e.g. .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

Answer 6

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

DocToc Command Line Tool (source) requires node.js

Installation:

npm install doctoc

Usage:

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