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

Question 1

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.

Question 2

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

Question 3

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

Question 4

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's README.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.

Question 5

Update Aug. 2021:

After ToC in README (see March 2021 below), you now have:

Table of content for Wikis

For Wikis we now automatically generate a table of contents based on the Markdown headings.

As illustrated here:

Do you wiki?
We just added an automatic table of contents to the sidebar to help with navigation

You can now (March 2021) check out what the CEO of GitHub Nat Friedman just announced

GitHub now automatically creates a table of contents for your http://README.md files from your headers.

After much consideration, we made this a feature of the viewer, not a concern of the editor: no special markdown to insert.

So... it does not modify your markdown (README.md or other .md files) to insert, or update your text: it only provides a menu which allows quick access to your test sections based on markdown headers.
That may, or may not, what you are after.

Question 6

https://github.com/jonschlinkert/markdown-toc

git clone your-repo.wiki.git (add the .wiki right before .git to clone the wiki
npm i -g markdown-toc
Insert  (case sensitive) in your wiki's markdown
markdown-toc -i my-wiki-markdown.md (-i will edit it in place)
Profit

Update: I think maybe https://github.com/thlorenz/doctoc is more popular now.

Question 7

Currently it's not possible to do that using markdown syntax (.md). There is ongoing unofficial discussion about automatically generating table of contents TOC on rendered markdown files like README.md which lists some of the ideas.

However there are some other workarounds such as:

Use AsciiDoc instead as per suggestion from this comment. For example:
```
:toc: macro
:toc-title:
:toclevels: 99
# Title

toc::[]

## A

### A2

## B

### B2
```
Check the example at littlebits/react-popover (README.adoc).
Online Table Of Content Generator (raychenon/play-table-of-contents)
arthurhammer/github-toc - browser extension that adds a table of contents to GitHub repos

Question 8

If you are not in the position to stick with Markdown, you can do as below:

on GitHub/wiki: switch Markdown to MediaWiki. Use __TOC__ Syntax. See sample.

on GitHub/repo: switch Markdown to AsciiDoc. Use :toc: Syntax. See demo.

on GitHub/repo: switch Markdown to reStructuredText. Use .. contents:: Syntax.

However, using Markdown files in GitHub/repo, you can get it on GitHub Pages like in Wikipedia

when Jekyll is activated, it generates GitHub Pages using Kramdown by default

Kramdown comes with Table Of Content. Use {:toc} Syntax. See the explanation.

Question 9

Due to the fact that github has it's own way of generating id=".." attributes in h1, h2, h3, etc... headers in html version after processing Markdown (for example Bitbucket use little different pattern of sluggifying headers title to id="slug") it is handy to don't reinvent the wheel and use library that reverse engineered this process.

I found one quite good library for this task called markdown-toc.

For me it seems the best solution because I always have installed node on my machine.

Just execute npx markdown-toc -i file.md.

And it looks like it is one of more popular tools for this task - at least in node.js ecosystem.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

output:

Question 10

You can choose the Edit mode "MediaWiki" which will generate a toc for the headers, e.g.

== First ==

== Second ==

Question 11

You can use mdtoc (I am the author).

Once installed, simply run:

mdtoc path/to/file.md

Question 12

One more TOC markdown related tool implemented on the top of Perl (which is shipped with Linux/Git-for-Windows always and with Cygwin optionally, and there are no dependencies on extra packages)

https://github.com/ildar-shaimordanov/git-markdown-toc

I guess my tool works similar or almost similar to ekalinin/git-markdown-toc mentioned above by other people. I have never compared tham because his tool is implemented as Go-Lang which doesn't exist on my system. The main goal of my script is to provide the good solution in creating TOC locally -- no any connection to any exteranl hosts and so on, only read a local file (README.md, by default) and create the TOC and embed it to the file.

Question 13

Example:

[Go to Delete](#delete_lines)

#delete_lines

code here, will be pointed here

See: https://guides.github.com/features/mastering-markdown/

And, to make a nested outline:

* 1\. [Go to Delete](#delete_lines)
    * 1.1\. item
    * 1.2\. item
        * 1.2\. item
* 2\. item

See: https://meta.stackexchange.com/questions/85474/how-to-write-nested-numbered-lists

And for more info and complex linking:

https://stackoverflow.com/questions/6695439/how-to-link-to-a-named-anchor-in-multimarkdown#:~:text=In%20standard%20Markdown%2C%20place%20an,%5Blink%20text%5D(%23abcd)%20.

Question 14

Pandoc is the Swiss army knife of markup. It can add a GitHub-compatible table of contents to a markdown file called README.md with this command:

pandoc --from markdown --to markdown --table-of-contents --standalone  README.md

The --from and --to options are required, and --table-of-contents requires --standalone. The options have short versions, so this is equivalent:

pandoc -f markdown -t markdown --toc -s README.md

By default the command prepends the table of contents and writes the result to stdout. Since you probably only want the table of contents itself, you might want to pipe to a pager to see the top of the file. For example:

pandoc -f markdown -t markdown --toc -s README.md | less

Other useful options are:

--toc-depth=NUMBER to specify the heading levels to include. The default is 3.
--output=FILE to write to a file instead of stdout.

See https://pandoc.org for installation and more usage instructions.