Markdown TOC Generator
Generate a GitHub-style table of contents from any Markdown document. Anchors auto-derived.
Indent:
Markdown input
Table of contents
Headings: 0
How Markdown anchor links work
GitHub and most Markdown renderers auto-generate anchor IDs from headings by lowercasing the text, replacing spaces with hyphens, and stripping special characters. So ## Getting Started becomes #getting-started. Paste your document, pick your indent style, and copy the generated TOC to the top of your file. For converting Markdown to HTML, try Markdown to HTML or use Markdown Converter.
Built and maintained by Meet Shah · Last updated
What this tool is used for
- Adding a table of contents to a long README.
- Regenerating a TOC after headings changed.
- Producing anchor links that match how the platform derives them.
- Checking heading structure by seeing the outline it produces.
- Generating a TOC for documentation that has no build step.
Frequently Asked Questions
- How are heading anchors generated?
- By slugifying the text: lowercase, spaces to hyphens, punctuation stripped. GitHub, GitLab and most static site generators each differ slightly on the details, so a TOC built for one may have broken links on another.
- What happens with duplicate heading text?
- GitHub appends -1, -2 and so on to later duplicates. A TOC that does not replicate this points every duplicate at the first occurrence — a common defect in long READMEs with repeated section names.
- How are emoji and code in headings handled?
- Inconsistently, which is the usual cause of a broken link. GitHub strips emoji from the anchor but keeps backtick-quoted code text, so `useState` Hook becomes usestate-hook. Guessing rather than following the target's rules is what breaks.
- Should I include H1?
- Usually not — the H1 is the document title and appears once, so listing it adds a level of nesting for no navigational value. Starting at H2 is the convention in most READMEs.
- Is a manual TOC still needed?
- GitHub now renders an automatic outline in the sidebar, so a manual TOC is redundant there. It still matters for files read outside GitHub, in editors, or rendered by a static site generator without that feature.
- Why do anchors differ between GitHub and other renderers?
- Because slug generation is not standardised. GitHub lowercases, strips punctuation and joins with hyphens; other renderers handle emoji, inline code and non-Latin headings differently — so a TOC that works on GitHub can break in a static site generator.
- How deep should a table of contents go?
- Usually two or three levels. Past that the TOC becomes as long as the document and stops functioning as an overview, which is the one thing it exists to provide.
Common errors and gotchas
- Assuming one anchor-slug convention, since GitHub, GitLab and static generators differ.
- Breaking links when a heading is renamed but the TOC is not regenerated.
- Including a heading that appears twice, where the second anchor gets a suffix.
- Generating a TOC from a document whose heading levels skip, which produces a broken outline.
- Including headings inside code blocks, which are not headings at all.
Related Text Tools tools
Case Converter
Convert between Sentence, Title, camelCase, snake_case, and more.
Word Counter
Count words, characters, and analyze keyword density.
Text to Binary
Convert text into its 8-bit binary representation.
Binary to Text
Decode 8-bit binary back into readable text.
Text Reverser
Reverse text by characters, words, or lines.
Remove Duplicate Lines
Delete repeated lines and keep your list unique.
Remove Empty Lines
Strip blank and whitespace-only lines from text.
Sort Lines Alphabetically
Sort lines A–Z or Z–A, case-sensitive or not.