Markdown Table of Contents Generator

Paste a Markdown document to instantly generate a nested table of contents with GitHub/Jekyll-style anchor links. Handles duplicate heading slugs correctly. Free, no signup.

Most docs skip H1 (the page title) and include H2–H4. Default is H2–H4.

Paste Markdown in the editor to generate a table of contents.

Markdown Table of Contents Generator

Paste a Markdown document and get a nested, linkable table of contents — generated instantly in your browser, with anchor slugs computed the same way GitHub and Jekyll/kramdown compute them. No signup, nothing uploaded.

Why the anchor-slug algorithm matters

A TOC is only useful if its links actually jump to the right heading. Every Markdown renderer auto-generates an id attribute for each heading based on its text, and that id is what a link like #my-heading has to match. Get the slug wrong and the link is dead. This tool uses the common algorithm:

  1. Lowercase the heading text
  2. Strip everything that isn't a letter, number, space, or hyphen
  3. Replace spaces with hyphens
  4. Strip leading/trailing hyphens
  5. If the resulting slug has already been used elsewhere in the document, append -1, -2, etc. — so two headings both called "Overview" become #overview and #overview-1

Duplicate-slug handling is the single biggest practical gotcha with hand-written TOCs — it's easy to write two headings with the same name (e.g. "Overview" under two different sections) and not notice that only the first one's TOC link actually works. This tool detects that automatically across your whole document, not just within the heading levels you've chosen to include, since a renderer numbers duplicates based on every heading it sees — not just the ones that end up in your TOC.

GitHub vs. GitLab vs. Jekyll/kramdown

In practice, GitHub, GitLab, and Jekyll (which uses kramdown, and is what powers GitHub Pages sites) all use slug algorithms that are extremely close to the steps above, and for the vast majority of plain-English headings they produce identical anchors. There are known edge-case differences we won't overclaim on: handling of underscores and emoji, how non-Latin/unicode characters are transliterated, and how numeric-only or symbol-only headings are deduplicated can vary slightly between renderers. If your headings use emoji, non-Latin scripts, or unusual punctuation, always spot-check the anchor against your target platform's actual rendered output before relying on it.

Heading level filtering

Use the min/max heading level controls to decide what belongs in your TOC. Most documents skip the H1 (it's usually the page title, already shown above the TOC) and include H2 through H4, which is why that's the default here. Even if you exclude a heading level from the TOC, its anchor slug is still accounted for when de-duplicating, so a link further down the document that reuses the same wording still gets the correct -1/-2 suffix.

Common use cases

  • README files — generate a jump-to-section TOC for a long project README
  • Documentation sites — build a manual TOC for platforms (like GitHub wikis) that don't auto-generate one
  • Long-form blog posts — add a TOC at the top of a long tutorial or guide for readability and SEO
  • Internal docs / RFCs — quickly navigate a long design doc without leaving the page

For a deeper walkthrough of building and maintaining TOCs by hand across different platforms, see our companion guide: How to Create a Table of Contents in Markdown.

Related tools