Generate a Markdown table of contents from your document headings
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [API Reference](#api-reference)
- [Methods](#methods)
- [Events](#events)
- [Contributing](#contributing)
- [License](#license)A table of contents is only useful if every link lands. These anchors follow GitHub’s own slug algorithm, so the TOC works when you paste it into a README:
#usage-1.| Heading | Anchor |
|---|---|
## Getting Started | #getting-started |
## API Reference (v2) | #api-reference-v2 |
## Setup & Config | #setup--config |
## What's New? | #whats-new |
## Café Setup | #café-setup |
The third row is the one that catches people out. Removing the ampersand from “Setup & Config” leaves two spaces behind, and GitHub turns each of them into a hyphen. Generators that tidy that into a single hyphen emit a link that silently goes nowhere.
Shell comments and Python comments both start with #, so a fenced code block in your README is full of things that look like headings. Line-based TOC generators happily add # Install dependencies from inside a bash snippet to your contents list.
This one tracks fence boundaries and skips everything between them, so only real headings are listed.
Convention is directly after the title and any badges, before the first real section. Many teams wrap it in HTML comments so an automated tool can refresh the block later without touching the rest of the file:
# My Project
<!-- toc -->
- [Getting Started](#getting-started)
- [Setup & Config](#setup--config)
<!-- tocstop -->
## Getting StartedGitHub also renders its own outline button on READMEs, but that is only visible on github.com — a TOC written into the file travels with the document to GitLab, npm, Obsidian, and anywhere else the Markdown is read.
Yes. The anchors follow github-slugger, the same algorithm GitHub uses: lowercase the heading, strip punctuation, keep letters from any language, and replace each remaining space with a hyphen. That last rule matters — removing the ampersand from "Setup & Config" leaves two spaces, so the correct anchor is #setup--config with two hyphens. Generators that collapse it to #setup-config produce a link that goes nowhere.
Duplicates get a numeric suffix in the order they appear, exactly as GitHub does it. Two "Usage" headings become #usage and #usage-1, so both TOC entries land on the right section instead of both jumping to the first one.
No. Shell and Python comments both start with #, so a fenced code block looks like a stack of headings to a naive line-by-line generator. This tool tracks fence boundaries and skips everything between them, so only real headings are listed.
Two or three works for most READMEs. Depth 2 gives a short scannable list of top-level sections; depth 3 suits long reference documents where readers jump straight to a subsection. Use the depth control above to compare before you copy.
Directly after the title and any badges, before the first real section. Wrapping it in <!-- toc --> and <!-- tocstop --> HTML comments is a common convention that lets automated tooling refresh the block later without disturbing the rest of the document.
The generated list is plain Markdown, so it renders anywhere. Anchor behaviour depends on the viewer: GitHub, GitLab, and most static site generators use this slug style, while some tools use their own prefixes. GitHub also shows its own outline button on READMEs, but that only exists on github.com — a TOC written into the file travels with the document everywhere.