Markdown Table of Contents Generator

Markdown heading anchors

Most Markdown renderers (GitHub, GitLab, VS Code preview) automatically create heading anchors by converting the heading text to a URL-safe slug. The rules:

• Convert to lowercase
• Replace spaces with hyphens
• Remove all non-alphanumeric characters except hyphens

TOC link format

## My Section Title

[My Section Title](#my-section-title)

When to use a TOC

A table of contents adds value for documents with 4+ headings and multiple sections. For short documents, a TOC adds noise without benefit. GitHub automatically shows a TOC button for markdown files with multiple headings.

GitHub vs GitLab anchor differences

The two most popular platforms handle special characters in heading slugs differently:

• GitHub: strips all characters except hyphens and alphanumerics. A heading ## foo(bar) becomes #foobar (parentheses removed).
• GitLab: also strips most punctuation, but handles a few edge cases differently - notably, dots in headings like ## v1.2 become #v12 on GitHub but may be handled differently on older GitLab versions.

If you are writing documentation that must work on both platforms, avoid parentheses, dots, and special characters in headings - stick to letters, numbers, spaces, and hyphens.

Where to insert the TOC

The conventional placement is after the document title (# Title) and any introductory paragraph, but before the first section heading (## Section). This mirrors the structure of academic papers and long-form documentation. Example:

# My Document Title

A brief introduction to the document.

## Table of Contents

- [Section One](#section-one)
- [Section Two](#section-two)

## Section One
...

Deeply nested headings

Including all heading levels (H1–H6) in a TOC often produces a long, hard-to-scan list. Most documentation guides recommend limiting the TOC to 2–3 levels of nesting (H1/H2/H3). H4–H6 are typically internal subsections that do not need top-level navigation links. If the tool generates deeper nesting than you want, delete or comment out the deeper entries after generating.