What it does
Scans your Markdown for headings (#, ##, ###, …) and builds a nested table of contents with GitHub-style anchor slugs. Pick the level range, for most READMEs you want H2 + H3, ignoring the H1 (which is the document title) and ignoring deeper headings.
The output is plain Markdown, bullet list with [text](#slug) links. Drop it at the top of any README, blog post, or doc page that supports anchor scrolling (GitHub, GitLab, most Markdown renderers).
Slug rules
The anchor slugs follow GitHub’s convention:
- Lowercase the heading text
- Strip all non-word characters (punctuation, emoji)
- Replace spaces with hyphens
- Collapse multiple hyphens into one
- Trim leading/trailing hyphens
So ## Setting Up the Frontend! becomes #setting-up-the-frontend. This matches what GitHub auto-generates when it renders a README.
What gets ignored
- Headings inside code fences:
\“ … ```blocks are skipped, so a# Comment` inside a Python code sample won’t show up in the TOC. - Headings outside the level range: if you set min=2, max=3, then H1, H4, H5, H6 are excluded.
- Headings with trailing hashes:
## Section ##is stripped of the trailing##per CommonMark spec. - Empty headings:
##with no text is excluded.
Common patterns
For a typical README:
- Min level 2, max level 3: skip the title (H1), include sections (H2) and subsections (H3). This is what most people want.
- Min level 1, max level 6: full document outline, including the title.
- Min level 3, max level 4: only deep nesting, useful for in-document subsection refs.
Why TOCs help
For docs longer than ~500 words, a TOC at the top:
- Lets readers see the structure before reading
- Provides direct deep-links so people can share specific sections
- Helps SEO, anchor links structure the page for search engines
GitHub auto-renders TOCs in PRs and issues if you use specific markers. For static sites and most docs, an explicit Markdown TOC is more reliable.
Frequently asked questions
Why does my heading show wrong slug?
GitHub’s slug rules have edge cases (consecutive duplicates get -1, -2 suffixes; some emoji handling differs). This generator uses the most common interpretation. For exact GitHub slugs in cases with duplicates, check what GitHub renders for your specific document.
Can I generate TOC for non-Markdown formats?
This tool handles Markdown only. For HTML, use a tool that walks <h1>-<h6> tags. For Word/Google Docs, those have built-in TOC generators.
Does the indentation matter? The output uses 2-space indentation per level, which works in CommonMark and GFM. Some older Markdown parsers prefer 4-space indentation; if your renderer mangles the nesting, the output likely needs more leading whitespace.
What if my document has no headings? The TOC panel shows “no headings in selected range”, either lower the min level, or your document genuinely lacks structure that benefits from a TOC.