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.
- Download the script https://github.com/ekalinin/github-markdown-toc
Feed your
README.md
to the script (as noted in Eugene'sREADME.md
)cat README.md | bash github-markdown-toc
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
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.
Just open Command Palette (Ctrl-Shift-P
) -> Markdown: Create Table of Contents
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)).