Markdown Table of Contents Generator
Paste a README or any Markdown file and get a linked table of contents. Anchors follow GitHub’s rules exactly — or GitLab’s, or Obsidian’s — and the TOC can be inserted into your document and refreshed later.
- Free
- No sign-up
- Runs in your browser
How the table of contents is built
The generator reads every heading in your Markdown — # headings and underlined (setext) headings — and skips anything inside code blocks or YAML front matter, so a # comment in a shell script never ends up in the TOC.
Each heading becomes a list item that links to its anchor. Anchors are made the way GitHub makes them: the text is lowercased, punctuation and emoji are removed, spaces become hyphens, and a heading that appears twice gets -1, -2 added, so ## Setup used twice links to #setup and #setup-1. Formatting inside headings is removed first: ` ## API: fetch() **options** links to #api-fetch-options`.
Choose “Document with TOC” to get your whole file back with the table of contents inserted after the title, between <!-- toc --> and <!-- tocstop --> markers. When you change headings later, paste the document in again and the existing TOC is replaced rather than duplicated — the same markers the markdown-toc tool and several VS Code extensions use.
Options explained
- From level / To level
- Which heading levels appear. The default, H2 to H3, suits most READMEs: the # title is the page itself, and deeper levels make the list long.
- Links for
- GitHub rules also match VS Code’s preview, GitHub Pages, MkDocs and most docs tools. GitLab collapses repeated hyphens (
#install-configure). Obsidian uses[[#Heading]]wiki-links. “No links” gives a plain outline. - List style
- Bullets (
-or*) or numbers. Numbered TOCs indent sub-items by at least three spaces so they nest correctly in every renderer. - Leave out the # title
- Skips the first level-1 heading when you include H1 in the range, so the document title does not link to itself.
Does my platform make a TOC by itself?
GitHub shows an outline menu for README and Markdown files automatically, but it is not part of the file, so it does not appear on npm, in other tools or when the file is printed — a written TOC does. GitLab and Azure DevOps wikis render a [[_TOC_]] tag as a live table of contents; on those, the tag is simpler than a generated list. Obsidian shows an Outline pane; a written TOC with [[#…]] links helps when you publish or export the note.
Frequently Asked Questions About Markdown TOC Generator
Comprehensive answers to common technical, formatting, security, and compatibility questions.
#setup-1). Links written by hand often miss one of these. Regenerate the TOC here, and make sure “Links for” matches where the file is shown — GitLab and Obsidian differ from GitHub.<!-- toc --> and <!-- tocstop --> (as “Document with TOC” writes it), paste the whole document here again with the same output selected: the old TOC is replaced with a fresh one in place.[[#Heading]] wiki-links, which jump to headings inside the same note. Obsidian’s Outline pane also lists headings, but it is not part of the note when you publish or export it.