Markdown TOC Generator: Build Clickable Tables of Contents in Seconds
Learn how the Markdown TOC Generator creates clickable tables of contents with GitHub, GitLab, and Pandoc anchor styles and configurable heading depth.
Table of Contents
Any Markdown document past a few hundred lines needs navigation. Without a table of contents, readers of a long README, technical specification, or guide are forced to scroll endlessly or rely on browser search to find what they need. A well-placed TOC solves that instantly — but writing one by hand is tedious, because every link must point to an exact heading anchor, and anchor syntax varies from platform to platform.
The Markdown TOC Generator automates the entire process. Paste your Markdown, choose an anchor style — GitHub, GitLab, or Pandoc — set how many heading levels to include, and you get a nested, clickable table of contents that you can copy straight back into your document.
The tool runs fully in your browser: it is free, requires no signup, and your content never leaves your machine. Whether you maintain open-source READMEs, internal wikis, or documentation sites, this guide explains how to use the generator effectively and how anchor styles differ.
Why Use the Markdown TOC Generator?
- Instant navigation for long documents. A TOC lets readers jump directly to the section they care about, which dramatically improves the reading experience for READMEs, specs, and long-form guides.
- Correct anchors on the first try. Hand-written anchor links break easily — one stray apostrophe, capital letter, or emoji and the link silently points nowhere. The generator computes each slug exactly the way your target platform does.
- Platform-compatible output. GitHub, GitLab, and Pandoc each slugify headings differently. The anchor style selector ensures the same heading produces the right link wherever the document renders.
- Configurable depth. Show only top-level sections for a compact overview, or include headings down to H6 for exhaustive technical references.
- Maintainable documentation. When you restructure headings, regenerate the TOC in seconds instead of auditing every link manually.
- Zero friction. Free, fully client-side, and no account required — paste, generate, copy.
Key Features
| Feature | What You Get |
|---|---|
| Heading parsing | Recognizes ATX-style (# Heading) and Setext-style (heading text underlined with === or ---) |
| Anchor style selector | GitHub, GitLab, or Pandoc slugification rules |
| Max depth control | Limit the TOC anywhere from H1 only through H1–H6 |
| Nested bullet output | A clean Markdown list of [text](#anchor) links that mirrors your heading hierarchy |
| Copy button | One click places the finished TOC on your clipboard |
| Download button | Save the TOC as a Markdown file |
| Clear button | Reset input and output instantly |
| Private by design | Runs entirely client-side — no uploads, no signup, completely free |
A few features deserve extra attention:
- Both heading syntaxes are supported. Whether you write ## Installation (ATX) or underline a line of text with --- (Setext), the parser picks it up, so mixed-style documents work without reformatting.
- Output is plain Markdown. The generated list drops into any Markdown renderer, static site generator, or wiki engine without post-processing.
- Duplicate headings are handled automatically. If two sections share the same title, the generator appends -1, -2, and so on, exactly as the target platform would.
How to Use the Markdown TOC Generator
- Paste your Markdown. Open the Markdown TOC Generator and paste your full document — or just the headings — into the input area.
- Choose an anchor style. Select GitHub, GitLab, or Pandoc depending on where the document will be rendered.
- Set the maximum heading depth. Pick H1 for a minimal outline or up to H1–H6 for a complete index.
- Generate and review the TOC. The tool outputs a nested bullet list of anchor links that mirrors your heading structure.
- Copy or download the result. Use the Copy button to grab the TOC, then paste it into your document — typically right after the introductory paragraph.
Here is a small example. Given this Markdown input:
# Getting Started ## Installation ## Configuration # Usage ## Basic Commands
The generator (GitHub style, depth H1–H2) produces:
- [Getting Started](#getting-started) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [Basic Commands](#basic-commands)
Understanding Anchor Styles: GitHub vs GitLab vs Pandoc
An anchor link only works if it matches the identifier the rendering platform assigns to a heading. Each platform derives that identifier — a "slug" — from the heading text using its own rules, so a link that works perfectly on GitHub can break on GitLab or a Pandoc-built site.
GitHub lowercases the heading, removes punctuation, and converts spaces to hyphens. For example, What's New in v2.0? becomes #whats-new-in-v20. When two headings produce the same slug, GitHub keeps the first unchanged and appends -1, -2, and so on to later duplicates — so a second Installation heading gets #installation-1.
GitLab follows a similar philosophy but strips more aggressively: it removes characters beyond lowercase letters, digits, hyphens, and underscores, which changes the slug for headings containing special characters, Unicode, or emoji. Duplicates receive the same -N suffix treatment, but because the base slug can differ from GitHub's, the final anchor often does too.
Pandoc — the engine behind many documentation sites, books, and static site pipelines — also lowercases and de-punctuates headings, but applies its own identifier rules, including special handling for headings that begin with numbers. If your site is generated with Pandoc or a Pandoc-derived toolchain, choosing the Pandoc style guarantees the links match the identifiers Pandoc actually emits.
Why does this matter? Broken anchor links are invisible until someone clicks them. In a README with fifty TOC entries, verifying each link against platform rules by hand is impractical. Selecting the correct anchor style up front eliminates an entire class of silent navigation failures.
Practical Use Cases
README Navigation
Open-source READMEs are the classic use case. A repository README with sections like Installation, Configuration, API Reference, and Contributing becomes far more usable with a TOC at the top. Generate it with the GitHub anchor style so every link resolves correctly on github.com.
Documentation Sites
Docs frameworks and static site generators render Markdown differently. If your pipeline is Pandoc-based, select the Pandoc style; for GitLab-hosted docs, choose GitLab. Limiting depth to H2 or H3 keeps the TOC concise while still covering every major page section.
Technical Specifications and Wikis
Long internal specs and wiki pages accumulate dozens of headings over time. A generated TOC gives reviewers a structural overview and lets stakeholders jump straight to the clause or requirement they need to discuss.
Blog Posts and Tutorials
Long-form technical posts benefit from the same navigation as documentation. Paste your post's headings into the generator, copy the TOC below your introduction, and give readers a roadmap before they commit to a ten-minute read.
Best Practices
- Keep headings descriptive and unique. Anchors derive from heading text, so clear, distinct headings produce stable links and reduce duplicate -N suffixes.
- Limit TOC depth to what readers need. Two levels is usually enough; a TOC that mirrors every H5 subheading overwhelms more than it guides.
- Place the TOC after a short introduction. Readers benefit from one or two sentences of context before the navigation block.
- Regenerate after restructuring. Whenever you add, remove, rename, or reorder headings, regenerate the TOC rather than patching links by hand.
- Prefer GitHub style for repository READMEs. If the document lives on GitHub, GitHub anchors are the only ones guaranteed to resolve.
- Check Setext headings before generating. The tool supports underlined headings, but converting them to ATX style first makes future edits more consistent.
Build Better-Navigated Documents Today
A clickable table of contents turns any long Markdown file from a wall of text into a navigable document — and it should take seconds, not an afternoon of slug arithmetic. Open the Markdown TOC Generator, paste your headings, pick your anchor style, and copy a TOC that works the first time. It is free, runs entirely in your browser, and never asks you to create an account.
Related Tools You Might Like
- Markdown Table Generator — Build perfectly aligned Markdown tables from pasted data without counting pipes.
- Markdown Preview — Render your Markdown live to verify headings, links, and formatting before you publish.
- Markdown to HTML Converter — Convert Markdown into clean HTML for embedding in websites, docs, or email templates.
Happy documenting!