Manual Method
A table of contents is just a list of anchor links pointing to your headings:
## Table of Contents
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
Anchor Link Rules
Markdown parsers automatically generate an ID for each heading. The ID follows these rules:
1. Lowercase the heading text 2. Replace spaces with hyphens 3. Remove special characters (punctuation, brackets, etc.)
Examples:
## Getting Started→#getting-started## API Reference (v2)→#api-reference-v2## What is it?→#what-is-it
Use the TOC Generator
Writing a TOC manually for a long document is tedious and error-prone. The Markdown TOC Generator reads your markdown, parses every heading, and generates the correct anchor links automatically. Paste your document, copy the TOC.
Where to Place the TOC
Place the TOC at the top of the document, just below the main title (# H1) and any introductory text. GitHub collapses it nicely above the first heading.
Platform Support
Anchor links work everywhere that generates heading IDs — GitHub, GitLab, Obsidian, most static site generators. They don't work in Discord or Slack (which don't generate heading anchors).
See also: Markdown Anchor Links and the TOC Generator tool.