TABLE OF CONTENTS
GENERATOR
Automatically generate a table of contents from Markdown headings. Creates clickable navigation links for better document organization.
TABLE OF CONTENTS FORMAT
HOW IT WORKS
- Paste markdown with headings (
#,##,###) - The tool reads the heading hierarchy and generates a nested TOC with anchor links
ANCHOR FORMAT
- Links use GitHub's anchor format: lowercase, spaces replaced with hyphens, special characters removed
- Compatible with GitHub README files and most markdown renderers
TIPS
- H1 headings (
#) are usually skipped in a TOC (they're the page title) - The tool includes H2 and H3 by default
- Paste the output at the top of your document
WHEN TO USE THIS TOOL
LONG GITHUB READMES
Your README has grown to cover installation, configuration, API reference, and troubleshooting. Without a TOC, readers have to scroll to find anything. Paste the whole file, copy the generated TOC, and drop it under your project description.
TECHNICAL DOCUMENTATION
You are writing a design doc, RFC, or internal wiki page with six or more sections. Adding a TOC at the top lets teammates jump straight to the section they need to review or comment on, rather than reading from the beginning.
BLOG POSTS AND GUIDES
You publish long-form tutorials in markdown, and your CMS or static site generator does not auto-generate a TOC. Paste the post source here, grab the TOC block, and include it manually before your introduction paragraph.
WHAT HAPPENS UNDER THE HOOD
HEADING EXTRACTION
The tool scans your markdown line by line and identifies any line that starts with one or more # characters. Each heading level becomes a level of nesting in the final TOC list.
ANCHOR SLUG GENERATION
For each heading, it generates a GitHub-compatible anchor slug: the heading text is lowercased, spaces become hyphens, and any character that is not a letter, number, or hyphen is stripped. So ## My API Reference becomes #my-api-reference. This matches exactly how GitHub renders anchor links in README files.
LIST FORMATTING
The output is a standard markdown unordered list. Sub-headings are indented with two spaces per level so the nesting is visible in the raw source and renders correctly in any markdown viewer.
FREQUENTLY ASKED QUESTIONS
DO THE ANCHOR LINKS WORK ON GITHUB?
Yes. The generated slugs follow GitHub's exact anchor format, so the links will work correctly when you paste the TOC into a GitHub README, wiki page, or any other file rendered on github.com. They also work on GitLab and most static site generators like Jekyll, Hugo, and Docusaurus.
WHAT IF I HAVE TWO HEADINGS WITH THE SAME TEXT?
GitHub handles duplicate headings by appending a counter: the second occurrence of ## Setup gets the anchor #setup-1, the third gets #setup-2, and so on. This tool reflects that behavior, so your TOC links will still point to the right sections even when headings repeat.
SHOULD I INCLUDE H1 IN MY TABLE OF CONTENTS?
Usually not. The H1 heading is typically your document title, and including it in the TOC creates a redundant link right at the top of the page. Most README conventions and style guides recommend starting the TOC from H2. The tool lets you configure which heading levels to include.
DOES THIS WORK WITH MARKDOWN INSIDE JSX OR MDX FILES?
It extracts any line that starts with # characters, so it will pick up headings inside MDX files. However, if your headings are written as JSX elements like <h2>Title</h2> rather than markdown syntax, those will not be detected. Stick to standard markdown heading syntax for full compatibility.
RELATED TOOLS
README GENERATOR
Generate a full README file structure from a project description, then add a TOC with this tool.
MARKDOWN FORMATTER
Clean up heading spacing and indentation before generating your TOC so the output nesting is correct.
MARKDOWN EDITOR
Write or edit your full document, then paste it here to generate the TOC and copy it back in.