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?

Related, but not exact duplicate, that goes into more detail: http://stackoverflow.com/q/9721944/2291 — Jon Adams, Jul 14 '16 at 18:03
Update March 2021 (almost 8 years later): GitHub can create automagically table of content for `README.md`. See [my answer below](https://stackoverflow.com/a/66824119/6309). — VonC, Mar 26 '21 at 20:48
Update Aug. 2021: GitHub can create automagically table of content of your ***wiki***! See [my edited answer below](https://stackoverflow.com/a/66824119/6309). — VonC, Aug 19 '21 at 21:37
GitHub now automatically generates a table of content for Wikis based on the headings. https://github.blog/changelog/2021-08-19-table-of-content-for-wikis/ — dipree, Aug 23 '21 at 11:10

score 159 · Accepted Answer · edited Jan 24 '22 at 14:12

159

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.

edited Jan 24 '22 at 14:12

DiskJunky

4,568
3
35
65

answered Aug 15 '13 at 00:30

RyPeck

6,981
3
38
57

66

Surely there's a way to autogenerate it like MediaWiki's _ _ TOC _ _? – LB-- Aug 12 '14 at 11:06
29

@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. – Andrew Janke Feb 17 '15 at 00:18
4

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. – Andrew Janke Feb 17 '15 at 00:26
7

@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. – LB-- Feb 18 '15 at 21:56
7

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. – t3chb0t Sep 07 '15 at 17:06
1

If you have section titles with spaces, replace them with hyphens: `[Tailing logs](#tailing-logs)` – Steve Tarver Dec 08 '18 at 16:43
Is there a way to add nesting to TOC ? – Ankit Deshpande Jan 30 '19 at 12:08

score 52 · Answer 2 · answered Feb 12 '19 at 06:08

52

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

answered Feb 12 '19 at 06:08

Bravo Yeung

6,946
3
31
41

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](https://gist.github.com/rachelhyman/b1f109155c9dafffe618#gistcomment-3310992). Edit: Bug has been reported to Github project. – Mr.Robot Dec 23 '20 at 07:34

score 39 · Answer 3 · edited Jun 20 '20 at 09:12

39

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

edited Jun 20 '20 at 09:12

Community

1
1

answered Apr 10 '20 at 16:09

np8

20,899
9
73
87

9

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. – twknab Feb 21 '21 at 00:44

John Tran · Answer 4 · 2016-05-22T14:16:19.587

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.

VonC · Answer 5 · 2021-08-19T21:32:54.730

25

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.

edited Aug 19 '21 at 21:32

answered Mar 26 '21 at 20:47

VonC

1,129,465
480
4,036
4,755

5

Note that this also works for other .md files, and is not exclusive to README's. – Kraigolas Apr 21 '21 at 19:02
1

@Kraigolas Great! That is convenient. – VonC Apr 21 '21 at 19:43
Note: June 2021: GitLab supports it also: https://twitter.com/tonka_2000/status/1399772594568638465 – VonC Jun 02 '21 at 17:50
@Kraigolas is it possible to make this work also in a gist .md file? – abu Feb 06 '22 at 09:33
@abu I didn't see that in gist for now. – VonC Feb 06 '22 at 20:50

corysimmons · Answer 6 · 2018-04-17T17:46:11.357

16

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.

edited Apr 17 '18 at 17:46

answered Nov 04 '16 at 17:06

corysimmons

6,464
4
50
58

score 15 · Answer 7 · edited Jun 29 '19 at 19:34

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

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. — Ciro Santilli Путлер Капут 六四事, Nov 09 '18 at 09:27

score 8 · Answer 8 · edited Jun 10 '21 at 17:33

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.

stopsopa · Answer 9 · 2020-01-02T22:40:02.033

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:

score 2 · Answer 10 · edited Nov 07 '17 at 09:36

2

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

== First ==

== Second ==

edited Nov 07 '17 at 09:36

fedorqui

252,262
96
511
570

answered Sep 23 '17 at 13:27

Stefan

7,735
3
43
96

True. See https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki for an example. – Agis Oct 16 '17 at 14:24

score 1 · Answer 11 · edited Sep 01 '21 at 22:58

1

You can use mdtoc (I am the author).

Once installed, simply run:

mdtoc path/to/file.md

edited Sep 01 '21 at 22:58

Dharman

26,923
21
73
125

answered Sep 01 '21 at 22:53

Teskann

11
1

If you can't build and install this, the next best thing is: `cat README.md | pandoc --from markdown --toc -s --to markdown -` – Sridhar Sarnobat Oct 02 '21 at 00:27

jsxt · Answer 12 · 2021-01-30T15:02:02.127

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.

score 0 · Answer 13 · answered May 19 '21 at 01:26

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.

score 0 · Answer 14 · edited Feb 16 '22 at 10:11

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.

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

14 Answers14

Visual Studio Code

Auto-update messes your edited TOC?

Table of content for Wikis

Linked