Markdown TOC Generator (Auto Table of Contents)

When you need a TOC

• Project READMEs: long files → readers jump to the section they need.
• Docs sites: Astro/Docusaurus auto-generate TOCs, but GitLab/GitHub markdown does not — add manually.
• Long blog posts: 3000+ word articles — a TOC at the top helps navigation and dwell time (good for SEO).
• Notion / Obsidian: paste a markdown export — get an instant outline.

Anchor link rules

GitHub/GitLab convert headings into slugs:

• Everything lowercase.
• Spaces → hyphens.
• Strip special characters (? ! : ...).
• Strip diacritics — Vietnamese accents stay in the slug if you don't strip!
• Duplicate headings → add -1, -2… suffixes.

Tips

• Strip Vietnamese diacritics: enable for clean ASCII slugs — works with GitHub and Hugo. E.g. "Cài đặt" → #cai-dat (NOT #cài-đặt).
• Min/max level: H2-H3 is usually enough. H1 is the post title → exclude. H4-H6 is too granular.
• Numbered + checklist: great for step-by-step tutorials (e.g. "Install", "Configure", "Run").
• Code blocks: the tool skips headings inside fenced code blocks ``` — no false positives from # comment in code.