Markdown TOC Generator

A table of contents from your headings

A TOC generator scans a Markdown document for heading lines (the ones starting with #) and builds a nested list of links to them. The number of hashes sets the level, so an h2 nests under the nearest preceding h1. Each link points to the slug that the renderer assigns to that heading.

How anchor slugs are formed

Most renderers derive a heading's anchor by lowercasing the text, replacing spaces with hyphens, and stripping punctuation. So ## Set Up & Config becomes the anchor #set-up--config. Knowing the rule matters, because the generated links must match exactly or they jump nowhere.

Example

Headings in the document:
  # Guide
  ## Install
  ## Usage
  ### CLI

Generated TOC:
- [Install](#install)
- [Usage](#usage)
  - [CLI](#cli)

The top-level h1 title is usually left out of the list itself, and the h3 indents under its parent h2 to show the hierarchy.

Pitfalls

Duplicate heading text produces duplicate slugs; renderers disambiguate by appending -1, -2, and so on, so the second "Overview" anchors to #overview-1. Emojis and non-Latin characters are slugged inconsistently across platforms, which is a common source of dead TOC links. Keep the heading levels sequential; skipping from h2 to h4 both confuses the nesting and hurts accessibility. The companion table generator covers the other structural piece of long docs.

FAQ

Do all platforms slug headings the same way? No. GitHub, GitLab, and various static site generators differ on punctuation and Unicode handling, so a TOC built for one may need tweaks on another.

How deep should the TOC go? Two or three levels is usually enough; listing every h4 makes the index as long as the content.

Can I keep it in sync automatically? Some tools insert the TOC between marker comments and regenerate it, so edits to headings update the list on the next run.