Create a Markdown TOC that keeps readers oriented
A table of contents turns a long README, documentation page, or set of notes into usable navigation. This generator does the repetitive part while leaving you in control of which headings appear.
How to create a table of contents in Markdown
You do not need to write every anchor by hand. Generate the nested list here, check it against the document preview, then paste it into your Markdown file.
Add your Markdown
Paste a document into the editor or upload a .md or .markdown file. The generator detects Markdown headings from H1 through H6.
Choose the heading depth
Set the first and last heading levels to include. For a typical GitHub README, choosing H2 through H3 keeps the TOC useful without exposing every small subsection.
Preview, copy, or insert the TOC
Use the preview to check that each generated link reaches the expected heading in this tool, then verify the finished document on its publishing platform. Select Copy TOC to paste the result yourself, or select Insert into Markdown to add a managed TOC after the document's first H1.
How headings become TOC links
The generated TOC keeps each heading's original text as the visible link label. Only the destination after the # is normalized: letters are lowercased, punctuation is removed, and spaces become hyphens. Unicode letters and numbers are retained. This also makes the tool a Markdown anchor link generator for the headings in your document.
For example, Getting Started becomes [Getting Started](#getting-started). If the same heading appears more than once, the visible labels stay the same while later destinations receive numeric suffixes such as #setup-1.
The preview uses this tool's own GitHub-style slug rules; it does not run GitHub's production renderer or guarantee identical heading IDs in every GitHub-compatible renderer. For the platform's reference behavior, see GitHub's documented section-link rules. Always verify the finished links on the platform where the document will be published.
| Markdown heading | Generated TOC entry |
|---|---|
Getting Started | [Getting Started](#getting-started) |
API Reference! | [API Reference!](#api-reference) |
What's New? | [What's New?](#whats-new) |
Setup (first occurrence) | [Setup](#setup) |
Setup (second occurrence) | [Setup](#setup-1) |
GitHub-style anchors, with clear compatibility limits
The generator detects Markdown headings from H1 through H6 and builds anchors for ordinary spaces, punctuation, repeated headings, and Unicode text. It does not call GitHub or GitLab, and its output is not tied to a tested version of either platform.
Raw HTML headings such as <h2 id="custom">Setup</h2> are not detected. Custom heading IDs written with renderer-specific attribute syntax are not read or preserved. Use Markdown headings and check any custom anchors in the final renderer.
GitHub Markdown TOC generator for README files
The generated anchors follow the GitHub-style behavior shown in the preview, including lowercase destinations and numeric suffixes for repeated headings. GitHub remains the final source of truth for a README after it is rendered.
GitLab and other renderers
If you need a GitLab Markdown TOC generator or publish through a wiki, documentation engine, or static-site generator, create the TOC here and verify every link there. Those renderers may normalize punctuation, Unicode, and duplicate headings differently.
List format
The generator currently returns a nested unordered list rather than an ordered list. If your document requires numbered entries, convert the list markers manually after copying the TOC.
Where a generated TOC helps most
GitHub READMEs
Give contributors a quick route to installation, usage, configuration, API notes, and troubleshooting without forcing them to scroll through the entire repository README.
Technical documentation
Make a long Markdown guide easier to scan before it moves into a docs site, wiki, or static-site workflow. Select only the levels that represent meaningful navigation.
Long notes and assignments
Add a compact outline to research notes, course material, or project handoffs while preserving the hierarchy already expressed by the headings.
Online generator, editor extension, or CLI?
This browser-based Markdown TOC generator is a good fit for a one-off README, a quick correction, or a file you do not want to send to a server. If headings change every day, an editor extension or CLI step may be a better way to regenerate the TOC as part of your normal workflow.
| Approach | Best for | Keep in mind |
|---|---|---|
| Online generator | Quick edits and one-off files | Regenerate after headings change |
| Editor extension | Frequent work in one editor | Requires installation and editor setup |
| CLI or CI step | Repositories with repeatable builds | Requires project configuration |
Why Markdown TOC links break
Most broken links come from a heading being renamed without regenerating the TOC, a renderer using a different slug rule, or duplicate headings receiving unexpected suffixes. Punctuation and non-English characters can also behave differently across platforms.
Regenerate the TOC after editing headings and check repeated titles. Use this tool's preview to confirm that each generated link reaches the expected heading, then verify the rendered file on the platform where readers will actually use it.
Generate a Markdown TOC without uploading your document
This client-side Markdown TOC generator reads the text and selected Markdown file in your browser. No signup is required, and the generator does not send the document to a conversion server. See the Privacy Policy for details about the site's other network requests and data-handling practices.