A table of contents for any Markdown file, in five seconds
Long documentation files (an 800-line README, a changelog, a deploy guide) are hard to read without a table of contents at the top. Readers want to jump to "Troubleshooting" or "API reference" with one click, not scroll ten screens.
This tool reads your Markdown, collects every heading (H1 to H6) and builds a nested bullet list with links to anchors. The links work straight away on GitHub, GitLab, Docusaurus, Astro and most static-site generators.
We skip headings inside fenced code blocks (`# is not an H1 if it sits inside \`\`\`bash`). The generator supports three anchor styles (GitHub, GitLab, plain), an "insert into document" mode, optional `<!-- TOC -->` markers for auto-update tools, and a "skip first H1" toggle.
How to use it
- Paste your Markdown into the left pane. A short sample is loaded by default so the tool has something to work with.
- Set the depth range with the sliders, defaults are H1 to H4. If you do not want the smallest headings, set max to H3. If you only want top-level sections, set max to H2.
- Pick an anchor style: GitHub (most common, also works on GitLab and Docusaurus), GitLab (very similar, small differences for leading digits), Plain (classic slugify, ASCII only).
- Enable "Numbered list" if you prefer `1.` over `-`. The numbers auto-adjust when rendered (GitHub shows 1, 2, 3 even if every entry is `1.`).
- "Skip first H1", if the first line of the file is the document title (e.g. the project name in a README), you usually do not want it in the TOC. Flip the switch.
- "Insert mode", instead of just the TOC, the generator returns the full document with the TOC inserted right after the first H1. Handy when you have an existing large file and want to add a TOC without manual editing.
- Copy the TOC (or the full document in insert mode) and paste into your file. Or download as a .md file.
When this is useful
Concrete situations where a table of contents pays off:
- A large open-source README. The file has 12 sections, "Installation", "Quick start", "Configuration", "API", "Examples", "Troubleshooting", "Contributing", "License". Without a TOC the user scrolls. With a TOC they click and land.
- A CHANGELOG.md with dozens of versions. A TOC linking to each version (`## v1.4.2, 2025-10-12`, `## v1.4.1, 2025-10-08`, ...) lets readers jump to the interesting release in one click. Generate the TOC once, append new versions on top, the TOC needs to be updated manually or by a tool like `markdown-toc`.
- Technical docs on Docusaurus / Astro / MkDocs. Some themes render a TOC in the sidebar automatically, but an in-page TOC still helps long articles. Generate it here, paste into the file, done.
- Migrating docs from Confluence / Notion. Exports from those tools rarely come with a usable TOC. Paste, generate, paste the result on top.
- A book or long-form article in Markdown. Technical books are often written in Markdown (Pragmatic Bookshelf, Manning). Each chapter needs a section index.
- Internal company docs. The infra repo README, an incident runbook, an onboarding doc, anything with more than 5 sections.
If you are building a README from scratch, use our README builder, it adds the TOC automatically. After tidying things up, run the file through our Markdown linter, it catches common anchor-link mistakes.