How Markdown Heading Anchors Actually Work
A markdown table of contents generator only works if its links actually match the anchor a renderer assigns to each heading, and that anchor comes from a specific, mostly-standardized slug algorithm: lowercase the heading text, strip punctuation, replace spaces with hyphens. GitHub, GitLab, and most static site generators follow this same GFM convention closely enough that markdown heading anchor links generated this way work across all of them without modification. The part people miss by hand: two headings with identical text produce a collision, GitHub's own renderer (and this tool) resolves it by appending -1, -2, and so on to every repeat after the first, an easy detail to get wrong when writing anchors by hand.
How to Use This Markdown TOC Generator
This markdown toc generator online works entirely from pasted text: paste your Markdown document, or just its headings, into the input field, results update automatically as you type, this tool doesn't just generate toc from markdown headings once, it can auto generate markdown toc output live on every keystroke. Set Min heading depth and Max heading depth to control which heading levels appear, for example min 2 / max 3 to skip a document's single H1 title and only list H2/H3 section headings. Pick a List style: dash for a plain bulleted list, numbered for an auto-numbered list that resets per level, or asterisk as an alternative bullet marker. Copy the generated linked list and paste it near the top of your document, above the headings it links to.
Dash vs Numbered vs Asterisk: Which List Style to Use
All three render identically as far as GFM cares, a bulleted or ordered list with nested indentation matching heading depth, so the choice here is purely stylistic and about matching the rest of your document's existing Markdown conventions. Numbered is the one functional standout: this markdown toc numbered list mode auto-numbers each heading level independently and resets the counter whenever a shallower heading appears, so inserting or removing a section never requires manually renumbering anything by hand.
| Style | Best For |
|---|---|
| Dash (-) | Most READMEs and general documentation, the most common convention |
| Numbered (1.) | Sequential guides, tutorials, or specs where section order matters visually |
| Asterisk (*) | Matching a document that already uses * for bullets elsewhere |
Common Mistakes When Hand-Writing a Markdown TOC
The most common failure is an anchor link that looks reasonable but doesn't match the renderer's actual generated slug, a heading with punctuation, mixed case, or extra spacing produces a specific slug that's easy to get subtly wrong by hand (a heading like "Setup & Install" doesn't slug to #setup-and-install, it strips the ampersand entirely). The second: forgetting that a repeated heading needs a -1, -2 suffix on every occurrence after the first, an easy detail to overlook when writing links manually. The third: hand-maintaining a numbered TOC through document edits, inserting a new section partway through means renumbering everything after it by hand, exactly the tedious, error-prone task this generator exists to eliminate.