ZapKit

Markdown Table of Contents Generator

Paste a Markdown document and get a nested table of contents with links to every heading, ready to drop into a README or docs page.

What is a Markdown TOC generator?

A table of contents lists a document's sections with links that jump straight to each one. Long READMEs, API docs, wikis and guides are much easier to navigate with one, but writing it by hand means working out every anchor and redoing it whenever a heading changes.

A TOC generator reads the headings in your Markdown, nests them by level and builds the anchor links automatically, in the format GitHub uses. Project maintainers use it for READMEs, technical writers for documentation, and students for long notes kept in Obsidian or similar Markdown apps.

How to use the Markdown Table of Contents Generator

  1. 1.Paste the document

    A README, a guide or any Markdown with headings.

  2. 2.Choose the depth

    Include headings down to H2, H3, H4 or all six levels, and leave out the title.

  3. 3.Paste the TOC in

    Put it near the top of the document, usually under the introduction.

Example: a user guide

A document with the H1 "User guide", H2s Installation, Configuration and FAQ & troubleshooting, two H3s under Installation, and a # line inside a code block:

Installation
[Installation](#installation)
On macOS (H3)
indented under Installation, #on-macos
FAQ & troubleshooting
#faq--troubleshooting
# inside the code block
ignored

Five entries in two levels, with the ampersand dropped from the anchor just as GitHub does.

Anchors that match GitHub

Each link points to the anchor GitHub, GitLab and most documentation sites generate: the heading in lowercase, punctuation removed and spaces turned into hyphens. Repeated headings get -1, -2 suffixes, just as GitHub numbers them.

Headings inside fenced code blocks are ignored, so a # comment in a shell snippet doesn't end up in the contents. Underlined headings (=== and ---) are recognised as well as # ones.

Frequently asked questions

Why doesn't a TOC link work on my site?

Some sites create anchors differently. GitHub's style is used here; check one heading's anchor on your site and compare.

Should the H1 be in the table of contents?

Usually not, since it's the document title. Leave Leave out the H1 title ticked.

Can I make a numbered TOC?

Yes. Tick Numbered list for 1., 2., 3. at each level.

Does it update automatically?

No. Paste the document again after changing headings to regenerate it.

More Developer tools