Markdown TOC Generator

Build a table of contents from Markdown headings.

Overview

Paste a Markdown document and the tool builds a nested table of contents from its headings, with anchor links matching GitHub's slug algorithm. Drop the result at the top of a README or long docs page and readers get a clickable outline.

It's for documentation maintainers and developers writing READMEs, RFC documents, or any long-form Markdown. Reach for it after a doc grows past the point where scrolling becomes a chore, or when sharing a draft and you want collaborators to be able to navigate easily.

How it works

The generator parses ATX-style headings (# through ######) and Setext-style underlined headings, ignores headings inside fenced code blocks, and emits a nested unordered list. Each entry is a Markdown link whose anchor follows GitHub's slugification rules: lowercase, replace whitespace with -, strip non-alphanumeric (except - and _), and append -1, -2, ... for duplicates.

GitHub Flavoured Markdown is the default target. The same anchors work in GitLab and most static site generators that follow GitHub's convention.

Examples

Input:

# Project
## Installation
## Usage
### Basic
### Advanced
## License

Output:

- [Project](#project)
  - [Installation](#installation)
  - [Usage](#usage)
    - [Basic](#basic)
    - [Advanced](#advanced)
  - [License](#license)

Duplicate headings get numeric suffixes:
```
## API   ->  #api
## API   ->  #api-1
```

Special characters stripped:

## Setup & Configuration  ->  #setup--configuration

FAQ

Will the anchors work everywhere?

GitHub, GitLab, and most static site generators use the same slug algorithm. If you're targeting a tool that uses a different scheme (some wikis), adjust the anchors manually.

Should I exclude H1?

Many READMEs use a single H1 for the title and a TOC that starts at H2. The generator lets you set the minimum heading level to skip the H1 line.

Are emojis preserved in anchors?

GitHub strips emojis from heading text when generating slugs but keeps them in the link text. The generator follows the same behaviour.

Does it auto-update on changes?

No - regenerate after editing headings. Plugins like doctoc automate this in CI; the manual approach works fine for small docs.

Try Markdown TOC Generator