How do I create some kind of table of content in GitHub wiki?

It is nicely demonstrated in the Table of Contents of the Markdown Cheatsheet.

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

If you hover over a Header in a GitHub Markdown file, you'll see a little link sample to the left of it, you can also use that link. The format for that link is <project URL#<header name>. The <header name> must be all lower case.


One possible (semi-automated) solution is Eugene Kalinin's github-markdown-toc. This tool essentially crunches through your README.md file and snarfs out #'s headings to create a TOC.

  1. Download the script https://github.com/ekalinin/github-markdown-toc
  2. Feed your README.md to the script (as noted in Eugene's README.md)

    cat README.md | bash github-markdown-toc

  3. Cut and paste generated TOC and place it at the top of your README.md file

Note that this bash implementation only works on Linux (from what I can tell).

As a side note, there is a golang implementation and is probably more of a hassle to get working.


Since github cannot use TOC directly, but we have other alternatives.

You can automatically generate TOC via Online tool:

Generate TOC Table of Contents from GitHub Markdown or Wiki Online

enter image description here

or via Local tool:

github-markdown-toc


Visual Studio Code

If you happen to use Visual Studio Code, there is easy-to-use extension called Markdown All in One that can make the TOC for any .md file in an instant.

enter image description here

Just open Command Palette (Ctrl-Shift-P) -> Markdown: Create Table of Contents

Original md After automatic TOC insertion

Auto-update messes your edited TOC?

As an additional tip, you might want to turn the "automatic TOC updates on save" OFF by using

  "markdown.extension.toc.updateOnSave": false,

in your Visual Studio Settings (Command Palette -> Preferences: Open Settings (JSON)).

Tags:

Wiki

Github