Markdown Table of Contents Generator
Free table of contents generator for markdown. Paste a document and get a linked TOC with GitHub, GitLab, Bitbucket or dev.to anchor styles.
Anchor rule: github-slugger; duplicates get -1, -2.
- [Getting Started](#getting-started) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Environment variables](#environment-variables) - [Installation](#installation-1) - [Contributing](#contributing) - [Guidelines](#guidelines) - [FAQ](#faq)
What Is a Table of Contents Generator?
A table of contents generator reads the headings in a markdown document and writes a nested list of links that jump to each section. Markdown itself has no TOC syntax, so the list has to be built from the heading text and the anchor id the hosting platform assigns to it. This markdown toc generator does both: it extracts H1 to H6 headings, builds an anchor for the platform you choose, and prints a markdown table of contents you can paste at the top of a README, wiki page or blog post.
It runs entirely in your browser. The sample document loaded on the page shows the typical cases: nested sections, a duplicated heading, a heading-like line inside a code block that must be ignored, and a setext heading underlined with dashes.
How to Generate a Markdown Table of Contents
- Paste your markdown into the left pane, or open a .md file.
- Pick the anchor style for the platform where the document will be rendered. GitHub is the default.
- Set the minimum and maximum heading depth. H2 to H4 is a common choice for long READMEs.
- Choose a bulleted or numbered list, the bullet character and the indentation width.
- Leave Skip first H1 on if the document title should not link to itself.
- Copy the list, or click Insert into document to place it after the title inside toc markers and download the whole file.
Anchor Styles by Platform
The same heading produces different anchors on different hosts. The generator applies these rules:
| Platform | "Getting Started: Part 2" | Duplicates |
|---|---|---|
| GitHub | #getting-started-part-2 | -1, -2 |
| GitLab | #getting-started-part-2 | -1, -2 |
| Bitbucket Server | #markdown-header-getting-started-part-2 | _1, _2 |
| dev.to | #getting-started-part-2 | -1, -2 |
| Azure DevOps | #getting-started-part-2 | -1, -2 |
| Plain | #getting-started-part-2 | -1, -2 |
GitHub keeps unicode letters, so a heading such as "Über uns" becomes #über-uns. The plain style strips accents to ASCII for static site generators that only accept letters, digits and hyphens.
Keeping the TOC in Sync with toc Markers
A hand-written table of contents drifts as soon as someone renames a heading. The Insert into document option wraps the generated list in <!-- toc --> and <!-- tocstop --> comments, which are invisible in the rendered page. Paste the document back into this github toc generator later and the block between the markers is replaced in place, so the rest of the file is untouched. The markers are the same ones used by the markdown-toc npm package and by editor extensions, so a document started here can be maintained from the command line later.
When to Use a Table of Contents Generator
Use a table of contents generator for any markdown file longer than one screen: README files with installation, usage and API sections, wiki pages, RFCs and long blog posts. GitHub shows an automatic outline in the file header, but that outline is not part of the document, does not appear on npm, GitLab mirrors or rendered docs sites, and cannot be numbered or limited to certain depths. A list in the document itself works everywhere the markdown is rendered.
Frequently Asked Questions
How does a table of contents generator make the links work?
Every markdown host turns a heading into an HTML id, and the table of contents generator reproduces that rule so each link points at the right id. GitHub lowercases the text, removes punctuation and replaces spaces with hyphens; other hosts differ slightly, which is why you pick an anchor style before copying.
Why do duplicate headings get -1 and -2?
Two headings with the same text would produce the same anchor, so the second one is suffixed with -1, the third with -2, and so on. GitHub, GitLab and dev.to all follow this pattern. Bitbucket Server uses an underscore instead (_1, _2), and the generator matches that when you choose the Bitbucket preset.
Does the markdown toc generator work with GitLab and Bitbucket?
Yes. Choose GitLab, Bitbucket Server, dev.to, Azure DevOps or a plain ASCII style from the anchor menu. Bitbucket Server prefixes every anchor with markdown-header-, and Azure DevOps percent-encodes punctuation, so a TOC copied from a GitHub README would break there without this switch.
Can I keep the TOC up to date automatically?
Use the Insert into document button. It wraps the list in <!-- toc --> and <!-- tocstop --> comments, and the next time you paste the document and insert again, the block between the markers is replaced rather than duplicated. The same markers are understood by markdown-toc and similar CLI tools.
Are headings inside code blocks included?
No. Lines that start with # inside a fenced code block (``` or ~~~) are comments or shell prompts, not headings, so the generator skips them. Setext headings, the ones underlined with === or ---, are recognised as H1 and H2.
Is my document uploaded?
No. The table of contents is generated in your browser; nothing you paste leaves your device.