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?
414 Answers
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.
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:
1Visual 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)).
1One 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
Feed your
README.mdto 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.mdfile
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.
0Update 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 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.
git clone your-repo.wiki.git(add the.wikiright before.gitto clone the wikinpm i -g markdown-toc- Insert
<!-- toc -->(case sensitive) in your wiki's markdown markdown-toc -i my-wiki-markdown.md(-iwill edit it in place)- Profit
Update: I think maybe is more popular now.
0Currently 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
AsciiDocinstead as per suggestion from this comment. For example::toc: macro :toc-title: :toclevels: 99 # Title toc::[] ## A ### A2 ## B ### B2Check 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
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.
Due to the fact that github has it's own way of generating 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) 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:
You can choose the Edit mode "MediaWiki" which will generate a toc for the headers, e.g.
== First == == Second == You can use mdtoc (I am the author).
Once installed, simply run:
mdtoc path/to/file.md 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)
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.
Example:
[Go to Delete](#delete_lines) #delete_lines code here, will be pointed here And, to make a nested outline:
* 1\. [Go to Delete](#delete_lines) * 1.1\. item * 1.2\. item * 1.2\. item * 2\. item And for more info and complex linking:
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=NUMBERto specify the heading levels to include. The default is 3.--output=FILEto write to a file instead of stdout.
