About Markdown TOC

Generate a table of contents from markdown headings. Part of the DevTools Surf developer suite. Browse more tools in the Text / String collection.

Use Cases

• Generating navigation for long README files in open-source projects
• Adding a table of contents to technical documentation
• Creating clickable TOCs for wiki pages in team knowledge bases
• Building navigation for Markdown-based static site content

Tips

• Paste your full Markdown document to auto-generate a TOC
• The TOC uses anchor links matching each heading's slug
• Regenerate the TOC whenever you add or rename headings

Fun Facts

• GitHub automatically renders a table of contents for Markdown files with 2+ headings via a clickable icon, but many platforms still require manual TOCs.
• The Markdown specification by John Gruber (2004) never included a table of contents feature — it remains an extension provided by various processors.
• Anchor links in Markdown TOCs work by converting headings to lowercase slugs, replacing spaces with hyphens and stripping special characters.

FAQ

How are heading levels handled?

H1 is usually the document title (not in TOC). H2–H6 become TOC entries with progressive indentation. Configurable — set the range to H3–H4 only if that fits your doc.

Does it handle duplicate headings?

Yes — if two headings have the same text, GitHub appends `-1`, `-2` suffixes to slugs. The TOC generator matches this behavior so anchor links work.

What about non-English headings?

The slug generator lowercases, strips punctuation, and replaces spaces with hyphens. Unicode letters (CJK, Cyrillic) are preserved; GitHub's algorithm matches.

Can I skip specific headings?

Add `<!-- skip-toc -->` inline with any heading and the generator excludes it. Useful for appendix sections or navigation headings.