Markdown table of contents generator
Build a README table of contents whose links land on the anchors GitHub actually generates — Chinese headings and duplicates included.
Input
Result
The result will appear here.A table of contents is only useful if every link lands somewhere, and hand-written anchors break in predictable ways: GitHub drops punctuation, keeps Chinese characters, lower-cases everything and numbers repeated headings -1, -2 in document order. This tool reads your Markdown, finds every heading outside code fences and front matter, and writes a nested list whose anchors follow the same rules as github-slugger, the library that mirrors github.com. It can also drop the list between <!-- toc --> and <!-- tocstop --> markers, the convention the markdown-toc command-line tool uses, so running it again replaces the old list instead of adding a second one.
How it works
- Both # headings and underlined (=== and ---) headings are found; lines inside ``` or ~~~ fences, YAML front matter and HTML comments are skipped.
- Anchors are made from the text GitHub renders: links, emphasis and inline code are reduced to their text, punctuation is dropped, spaces become hyphens.
- Every heading counts towards the -1, -2 numbering of duplicates, including the ones deeper than the depth you chose, because GitHub numbers them all.
- Set the maximum depth, the bullet style, whether the document title (a leading H1) is left out, and whether to return the whole document with the list inserted between the markers.
Where your data goes
Nowhere. This tool runs entirely in your browser: the text you paste is processed by the page and is never transmitted to a server or written to a log.
This tool is free and needs no account. Its results exist only in your open page and are not saved anywhere.
What it costs
This tool is free, with no sign-in and no points.
Common questions
- Why does the anchor for a Chinese heading keep the characters?
- Because GitHub keeps them. Its slug rule removes only punctuation and symbols, so ## 安装与使用 links to #安装与使用 and ## FAQ：为什么选择 Rust？ to #faq为什么选择-rust — the full-width colon and question mark go, the characters stay. Browsers percent-encode the link when they follow it, which is expected.
- Will the links work on GitLab or Gitea?
- Mostly. GitLab and Gitea slug headings in a very similar way, and simple English headings produce the same anchor everywhere. They differ in edge cases — repeated headings, some punctuation, non-Latin text on older versions — so for a site other than GitHub, click through the links once after publishing.
- How do I update the TOC after adding sections?
- Put <!-- toc --> on its own line where the list belongs and <!-- tocstop --> after it, turn on inserting between markers, and run the whole document. Everything between the markers is replaced, and headings inside the old list are ignored, so running it again gives the same result instead of a list that grows each time.
- Does it read headings written in HTML, like <h2>?
- No. Only Markdown headings are listed — # lines and lines underlined with === or ---. An <h2> tag in the Markdown is left out of the list; rewrite it as ## if you want it included.
The open-source behind it
This tool is a self-contained implementation. jonschlinkert/markdown-toc (MIT) does the same job as a library — if you need this behaviour inside your own program, start there rather than calling a web page.
jonschlinkert/markdown-tocAlso known as
- markdown table of contents generator
- markdown toc
- readme toc generator
- github markdown anchor links
- generate toc for readme
- markdown toc chinese headings