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

Question

If you look here: http://en.wikipedia.org/wiki/Stack_Overflow

You'll notice there's a little "Content" section, if you click on one of the links, it will send you to a specific section on the page.

How do I do this in GitHub wiki? With Markdown or whatever they use?

Ribble

Related, but not exact duplicate, that goes into more detail: https://mcmap.net/q/64592/-automatic-toc-in-github-flavoured-markdown/2291 – Hoarse

Update March 2021 (almost 8 years later): GitHub can create automagically table of content for README.md. See my answer below. – Laris

Update Aug. 2021: GitHub can create automagically table of content of your wiki! See my edited answer below. – Laris

GitHub now automatically generates a table of content for Wikis based on the headings. github.blog/changelog/2021-08-19-table-of-content-for-wikis – Chirp

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

Hedgehop

Surely there's a way to autogenerate it like MediaWiki's _ _ TOC _ _? – Tupiguarani

@LB--: If you edit a GitHub wiki page and change the "editing style" dropdown to "MediaWiki", you can just use the MediaWiki __TOC__ directly. Clearly the underlying autogeneration logic is there. But the functionality doesn't seem to be exposed in their Markdown editing style. Quite unfortunate. Let's all start sending in feature requests for it and maybe they'll turn it on. – Volva

I recant on the "underlying autogeneration logic" being there; it looks like the different "editing styles" go through different renderers. Still, it would be great to have this in the MD version since that's pretty popular, and couldn't be hard to add. – Volva

@AndrewJanke I looked into it more, it seems that the MarkDown format doesn't have any support for autogeneration of tables of contents, and they're proud of it. – Tupiguarani

There is one catch in creating links. They have to be lower case. I didn't know that and was wondering why my TOC isn't working. I used #Headers instead of #headers. I thought it was a typo in your answer. Perhaps you can add to your answer this information. – Toogood

If you have section titles with spaces, replace them with hyphens: [Tailing logs](#tailing-logs) – Thynne

Is there a way to add nesting to TOC ? – Alvaalvan

Answer 2

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

Acridine

This was so helpful..from spying your answer to having a TOC on my github repo = ~3 min. Great answer thanks so much, looking forwards to using this plugin in other cases as well. – Cladding

Answer 3

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

Grapevine

The online tool doesn't work with headers like this: "# Chapter 1: Introducing to something". Symbol : is replaced with hyphen, but it should be removed altogether as per explanation. Edit: Bug has been reported to Github project. – Nepheline

Answer 4

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.

Laris

Note that this also works for other .md files, and is not exclusive to README's. – Audition

@Audition Great! That is convenient. – Laris

Note: June 2021: GitLab supports it also: twitter.com/tonka_2000/status/1399772594568638465 – Laris

@Audition is it possible to make this work also in a gist .md file? – Quelpart

@Quelpart I didn't see that in gist for now. – Laris

Unfortunately this isn't available for the markdown documents in the wikis. So it doesn't answer the question. (that icon doesn't exist in the wiki docs). – Latterday

@Latterday Strange, I cannot find a trace of this reversal on GitHub blog. – Laris

Answer 5

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.

Podiatry

Answer 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 <!-- toc --> (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.

Cyanine

Answer 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

Lightless

Yes, I have been converted to asciidoc largely for the ToC and linking to headers. Got fed up of waiting for Markdown to catch up. – Jaunty

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

Silicon

Answer 9

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

== First ==

== Second ==

Faubourg

True. See github.com/bitcoin/bips/blob/master/bip-0174.mediawiki for an example. – Cromagnon

Answer 10

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:

Lacuna

Answer 11

Pandoc

The swiss army knife of markup:

cat README.md | pandoc --from markdown  --toc -s  --to markdown -

Florio

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

Deteriorate

dear jsxt - good day i am urgently in need of having the newest markup manual - which is the best one here the most actual one!? – Exudate

@zero, i am not sure that I understand you. If you need a manual, you can find any of them in google. If you need advice on what kind of tools you need, you have to read their descriptions, try and make your decision which one is better in your case. – Deteriorate

Answer 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://mcmap.net/q/53691/-how-to-link-to-a-named-anchor-in-multimarkdown#:~:text=In%20standard%20Markdown%2C%20place%20an,%5Blink%20text%5D(%23abcd)%20.

Wilhelmina

dear folks i am urgently in need of having the newest markup manual - which is the best one here the most actual one!? – Exudate

Answer 14

You can use mdtoc (I am the author).

Once installed, simply run:

mdtoc path/to/file.md

Ascidian

If you can't build and install this, the next best thing is: cat README.md | pandoc --from markdown --toc -s --to markdown - – Florio