Markdown Table of Contents (TOC) Generator — Auto Headings

How to TOC Generator in 3 Simple Steps

1. Paste Markdown Document Paste your Markdown notes, README, or technical documentation into the source editor.
2. Heading Tree Analysis & Slug Generation The generator scans all heading levels, creates URL-safe slugs (e.g., #system-overview), and builds an indented navigation list.
3. Insert TOC & Export Insert the generated TOC at the top of your document or copy it separately for your README or wiki.

Deep Technical Architecture: Deterministic Slug Generation

MarkItDown Web Studio is engineered for deterministic, high-fidelity transformation. Rather than relying on lossy text scraping, our architecture parses documents down to their underlying AST (Abstract Syntax Tree):

• GitHub Flavored Slug Generation: Normalizes heading strings into lowercase, hyphenated URL fragments matching GitHub's exact anchor algorithm.
• Multi-Level Nesting: Applies 2-space indentation per heading depth (H1 -> H2 -> H3 -> H4) for structured navigation.
• Duplicate Heading Disambiguation: Appends numerical suffixes (-1, -2) to duplicate headings to prevent broken anchor collisions.
• Punctuation Stripping: Safely removes question marks, exclamation points, and special characters from anchor links.

The LLM & RAG Advantage: Why Markdown Wins

Large language models (OpenAI GPT-4o, Anthropic Claude 3.5 Sonnet, Google Gemini 1.5 Pro) and embedding models consume textual tokens. Passing binary files, raw XML, or noisy DOM trees drastically degrades retrieval accuracy:

By transforming raw documents into clean Markdown, your vector retrieval pipelines gain clear structural boundaries, higher cosine similarity scores, and zero token bloat.

Feature Comparison: MarkItDown Studio vs. Alternative Solutions

Developer API & Automation Snippet

Need programmatic conversion? Call our REST API endpoint directly from your terminal or ingestion backend:

# Python Example: Auto-Generate Markdown TOC
import requests

doc = "# Architecture\n## Database\n## Cache"
res = requests.post(
    "https://markitdown.site/api/process/toc",
    json={"markdown": doc}
)
print(res.json()["markdown"])

GitHub Anchor Slug Generation Specification

GitHub uses a specific algorithm to generate internal anchor identifiers for Markdown headings. Violating these rules results in broken in-page navigation links. MarkItDown Web Studio faithfully reproduces GitHub's canonical slugification rules:

• Punctuation Removal: Strips special characters including colons, commas, semicolons, brackets, and quotes.
• Whitespace Normalization: Replaces consecutive whitespace spaces and tabs with a single hyphen (-).
• Case Insensitivity: Transforms all characters to lowercase English letters ([a-z0-9-]).
• Duplicate Disambiguation: Appends numeric counters (-1, -2) in order of appearance when multiple identical headings exist.

Frequently Asked Questions