Markdown TOC Generator

Runs 100% in your browser

Generate a linked table of contents from any Markdown document — ATX and Setext headings, anchor-safe GitHub slugs, duplicate disambiguation, hierarchical numbering.

Min level Max level Numbering Slug mode Honour {#id} Add TOC heading

MARKDOWN SOURCE

Paste your document

Ctrl+Enter to generate & save

GENERATED TOC

Copy-ready output

Paste or type Markdown above to generate a TOC.

TOC STATS

Analysis

Headings found0

In TOC0

Depth range—

Duplicate slugs0

TOC lines0

TOC bytes0

SESSION HISTORY

Frequently asked questions

What is a Markdown TOC Generator?

A Markdown TOC Generator reads the heading structure of a Markdown document — lines starting with # through ###### or underlined with === and --- — and produces a list of anchor links that form a clickable table of contents. Each link uses a slug derived from the heading text, following the same algorithm used by GitHub, GitLab, or your chosen Markdown renderer.

How does ToolsSonic generate anchor slugs?

In GitHub-like mode, slugs are lowercased, non-alphanumeric characters are removed (Unicode letters and numbers are kept), and spaces become hyphens. In Clean ASCII mode, only a-z, 0-9, and hyphens are retained — useful for renderers that do not support Unicode anchors. Both modes disambiguate duplicate headings by appending -2, -3, and so on.

What are ATX and Setext headings?

ATX headings use a # prefix: # H1, ## H2, up to ###### H6. Setext headings use an underline on the next line: a line of equals signs (===) for H1 or a line of hyphens (---) for H2. Both styles are fully supported by this generator.

Why are headings inside fenced code blocks excluded?

Fenced code blocks (delimited by ``` or ~~~) represent source code, not document structure. Including headings found inside code samples would produce incorrect TOC entries. The generator tracks fence open/close state and ignores any # lines encountered inside a code block. A warning badge is shown when such lines are detected.

What is a {#custom-id} anchor?

Some Markdown flavors — including Pandoc, kramdown, and many static-site generators — let you attach a custom anchor to a heading by appending {#your-id}. For example: ## Installation {#install}. When the "Honour {#id}" option is enabled, this generator extracts the custom anchor and uses it as the slug instead of computing one from the heading text. The {#id} suffix is also stripped from the displayed link label.

How does duplicate slug disambiguation work?

When two headings produce the same base slug, GitHub appends -2, -3, etc. to the duplicates. This generator follows the same rule: the first occurrence keeps the base slug, the second becomes base-2, the third becomes base-3, and so on. The Duplicate slugs stat shows how many base slugs were affected.

What depth range should I use?

For most README files, H2–H4 (the default) is a good balance: H1 is usually the document title and does not need a TOC entry, and levels below H4 rarely need navigation links. For long technical docs or wikis you may want H2–H6. For a shallow document summary, H2–H3 is often sufficient.

What do the three numbering modes do?

Bullet mode produces an unordered list using - markers, which is the most widely supported format. Ordered mode uses 1. markers for all items (most Markdown renderers auto-increment). Hierarchical mode adds a 1.1.2. style prefix to each link label so readers can see the nesting at a glance — useful in printed documentation or when the rendered TOC lacks indentation.

Can I generate a TOC from a local Markdown file without uploading it?

Yes. Click "Open .md" to load a .md or .markdown file from your device. The file is read by the browser's FileReader API entirely in memory — it is never uploaded to any server. All processing happens locally on your device.

Will the generated anchors match GitHub exactly?

Yes. The GitHub-like slug mode matches GitHub's heading anchor algorithm exactly: lowercase, strip punctuation (keeping Unicode letters and numbers), replace spaces with hyphens, and append -2/-3 for duplicates. The generated TOC can be pasted directly into your README.md and all links will resolve correctly on GitHub. The anchor-safe slug mode ensures no special characters can break the anchor link.

Does it work with GitLab Markdown?

Yes. GitLab uses a slug algorithm very similar to GitHub's. Select GitHub-like slug mode and the generated links will resolve correctly in GitLab README files, wiki pages, and merge request descriptions.

Does it work with MkDocs, Hugo, or Obsidian?

MkDocs uses Python-Markdown which supports {#id} anchors via the attr_list extension — enable "Honour {#id}" and add anchors where you want exact control. Hugo's Goldmark renderer uses the same GitHub-like slugging algorithm by default. Obsidian uses lowercase slugs with spaces converted to hyphens. In all three cases the GitHub-like slug mode produces correct results. For Pandoc or kramdown, explicit {#id} anchors give you the most portable output.

How does session history work?

Each time you click "Copy TOC", "↓ .md", load a sample, open a file, or press Ctrl+Enter, the current Markdown source and generated TOC are saved as a history entry (up to 8 entries). Click "Restore" next to any entry to reload that source into the editor and regenerate the TOC. History is stored in memory for the current browser session only — it is never persisted to localStorage or a server.

What does the heading map tab show?

The Heading Map tab displays a table of every heading matched by the current depth filter, showing its H-level badge, display text, computed anchor slug, and source-line number. This is useful for debugging duplicate slugs, verifying that {#id} anchors were recognised, and checking that headings inside code blocks were correctly excluded.

What do the 6 stats represent?

"Headings found" counts all headings in the document (all levels, no filter). "In TOC" counts only the headings that passed the min/max depth filter. "Depth range" shows the H-level span of the filtered set. "Duplicate slugs" shows how many base slugs appear more than once before disambiguation. "TOC lines" is the line count of the generated markdown. "TOC bytes" is the UTF-8 byte size of the generated markdown.

How does this compare to BitDownToc?

BitDownToc supports GitHub/GitLab/Hashnode/dev.to platform presets, a [TOC] insertion marker, configurable indentation, and HTML/Liquid regeneration markers. However, it only handles Latin-script text for slug generation (no Cyrillic, CJK, Arabic) and does not offer heading map inspection, {#id} anchor support, hierarchical numbering, a file-open button, or a session history panel. ToolsSonic handles Unicode text fully, provides 3 numbering modes, shows a source-line map, and works with any Unicode language.

What is the Include TOC heading option?

When enabled, the generator prepends a "## Table of Contents" heading above the TOC list. This is useful when you are inserting the TOC into a document that does not already have a "Contents" section label.

Can I use this for API documentation?

Yes. Large API reference docs — especially those authored in Markdown and published with MkDocs, Docusaurus, VitePress, or similar tools — benefit greatly from a generated TOC. Paste the full doc source, set the depth range to cover your method/section headings, and copy the output to the top of your document or into a sidebar config.

Does the tool handle Markdown with frontmatter?

YAML frontmatter (--- delimited blocks at the top of the file) is treated as a fenced region by most parsers, but the generator does not have special frontmatter handling. If your frontmatter contains lines that look like headings, you can simply delete them from the source before generating — or use the Min Level setting to exclude H1 if your frontmatter title is the only H1 in the doc.

Is there a size limit?

There is no hard size limit. The generator processes Markdown entirely in the browser. Very large documents (hundreds of headings) will still process instantly. The only constraint is the browser's available memory, which is practically unlimited for text files.

What happens if two headings have the same text at the same level?

They receive different slugs: the first keeps the base slug (e.g. #installation) and each subsequent one gets a numeric suffix (#installation-2, #installation-3). This exactly matches GitHub's disambiguation algorithm so all links resolve correctly. The "Duplicate slugs" counter in the stats panel shows how many base slugs were affected.

Is the Markdown TOC Generator free?

Yes. ToolsSonic's Markdown TOC Generator is completely free with no account, no rate limit, no watermark, and no file size limit. All features — ATX and Setext parsing, both slug modes, all numbering modes, {#id} support, heading map, 6-stat panel, session history, copy, and .md download — are available at no cost, with no ads or paywalls.

What is Markdown TOC Generator?

What is a Markdown TOC Generator?

A Markdown TOC Generator reads the heading structure of your Markdown document and produces a list of anchor links — a table of contents — ready to paste into any README, wiki, API reference, or documentation page. You paste your Markdown source, the tool scans every heading (ATX # through ###### and Setext underlined headings), computes anchor slugs, and emits a clean, indented, clickable list in under a second.

Writing a TOC by hand is tedious and fragile. Every heading change means updating the TOC manually. Every duplicate heading needs a -2 suffix that is easy to forget. Every Unicode character in a heading needs the correct slugging treatment. A generator handles all of this automatically, and handles it correctly for every Markdown renderer you might use: GitHub, GitLab, MkDocs, Hugo, Obsidian, Docusaurus, VitePress, Pandoc, or kramdown.

ToolsSonic's Markdown TOC Generator runs entirely in your browser. No file is ever uploaded, no account is needed, and no network request is made during processing. You can verify this by opening DevTools → Network while generating a TOC — zero bytes leave your device.

Features That Beat Every Competitor

Most online TOC generators offer a single textarea, one slug mode, and a copy button. ToolsSonic goes further on every dimension that matters:

ATX and Setext heading support — Both # ATX headings and Setext headings underlined with === (H1) or --- (H2) are parsed and included. This matches the CommonMark specification and handles documents produced by legacy Markdown tools that output Setext-style headings.

Fenced-code-block exclusion — Headings inside ``` `` or ~~~` fenced blocks are ignored. If you have a code example showing how to write a heading, it will not pollute your TOC. A warning badge is shown when such headings are detected, so you can confirm they were intentionally skipped.

Depth filter (H1–H6) — Choose a min and max heading level to include. The default H2–H4 is ideal for most README files. Bump it to H2–H6 for deep technical references, or narrow it to H2–H3 for a lightweight summary TOC.

Three numbering modes — Bullet mode (- [link]) is universally supported and the safest default. Ordered mode (1. [link]) auto-increments in all renderers. Hierarchical mode prefixes each item with 1.1.2. so the depth hierarchy is visible even in renderers that strip indentation. No competitor offers hierarchical numbering.

Two slug modes — GitHub-like mode keeps Unicode letters and numbers (supporting Cyrillic, CJK, Arabic, Devanagari, and every other script), lowercases everything, and replaces spaces with hyphens. Clean ASCII mode strips everything except a-z, 0-9, and hyphens — useful for legacy renderers. BitDownToc, the closest competitor, only handles Latin scripts; ToolsSonic works with any language.

Explicit {#id} anchor support — Pandoc, kramdown, Hugo, Jekyll, and MkDocs allow ## Heading {#custom-anchor} syntax. When enabled, the generator honours these custom IDs as the anchor slug and strips the {#id} suffix from the displayed label. This is essential for documentation that needs stable anchor links even when heading text changes.

Duplicate slug disambiguation — When two headings produce the same base slug, the generator appends -2, -3, etc., exactly matching GitHub's algorithm. The "Duplicate slugs" stat counter shows how many base slugs were affected so you can decide whether to reword headings.

Heading Map panel — A sortable table showing every filtered heading with its H-level badge, display text, computed anchor slug, and source-line number. This is invaluable for debugging anchor links, confirming {#id} recognition, and verifying code-block exclusions. No other free online tool offers this.

6-stat panel — Live counts for: headings found, headings in TOC, depth range, duplicate slugs, TOC lines, TOC bytes.

Session history (8 entries) — Every generate action saves a snapshot of the source and TOC. Click "Restore" to reload any previous version. Stored in memory only — nothing is persisted.

Open .md file — Load any .md or .markdown file directly from your device using the browser's FileReader API. The file never leaves your machine.

Copy + Download — Copy the TOC to clipboard with one click, or download it as a .md file.

280 ms live debounce — The TOC updates automatically as you type, with a 280 ms debounce to avoid thrashing on large documents.

Anchor Slugs Across Markdown Renderers

Not all Markdown renderers create anchor slugs the same way. Using the wrong algorithm means your TOC links silently fail. Here is what each major renderer does:

GitHub strips all characters except Unicode letters, numbers, spaces, and hyphens; lowercases; replaces spaces with hyphens; and appends -2, -3 for duplicates. A heading like ## Настройка becomes #настройка. Select GitHub-like mode to match this exactly.

GitLab follows the same algorithm as GitHub for most headings. GitHub-like mode produces correct links for GitLab README files and wiki pages.

CommonMark / Pandoc do not define a heading anchor algorithm at all — the anchor is determined by each tool's implementation. Pandoc's default is to use the heading text lowercased with spaces replaced by hyphens and most punctuation stripped. The {#id} syntax provides a renderer-independent escape hatch: you control the anchor and it stays stable regardless of tool.

Hugo (Goldmark) uses the same GitHub-like algorithm by default. GitHub-like mode is the correct choice for Hugo projects.

MkDocs (Python-Markdown) lowercases and replaces spaces with hyphens, but strips Unicode characters in default mode. Use Clean ASCII mode, or enable {#id} anchors with the attr_list extension for full control.

Obsidian uses lowercase slugs with spaces as hyphens and strips most punctuation. GitHub-like mode produces compatible links.

Docusaurus / VitePress use GitHub-like slugging. GitHub-like mode is correct for both.

For maximum portability across all renderers, use explicit {#id} anchors on headings where you need stable links, and let the generator use those IDs verbatim.

Common use cases

Adding a clickable table of contents to a GitHub README file — H2 and H3 headings, correct anchor slugs, no manual linking
Generating a TOC for a long API reference document published with MkDocs, Docusaurus, VitePress, or Hugo
Creating navigation links for a GitLab wiki page, Bitbucket README, or Azure DevOps wiki
Producing a hierarchically numbered outline (1.1.2.) for printed technical documentation or a PDF-exported Markdown file
Debugging anchor links in an existing document — using the Heading Map to check computed slugs and source-line numbers
Handling documents with duplicate heading text — verifying that disambiguation suffixes (-2, -3) are applied correctly
Processing documents with Unicode headings (Cyrillic, CJK, Arabic) — using GitHub-like mode to preserve non-ASCII characters in anchors
Using explicit {#id} anchors with Pandoc or kramdown to produce stable, renderer-independent anchor links

Why use ToolsSonic's Markdown TOC Generator?

ToolsSonic's Markdown TOC Generator is the only free browser-based tool that combines all of the following without any account, upload, or network call: ATX and Setext heading parsing, fenced-code-block exclusion with warning badge, configurable depth filter (H1–H6), three numbering modes (bullet / ordered / hierarchical), two slug modes (GitHub-like Unicode and Clean ASCII), explicit {#id} anchor support, duplicate slug disambiguation with GitHub-exact algorithm, a Heading Map panel with H-level badges and source-line numbers, a 6-stat panel, 8-entry session history with restore, local .md file loading, copy and download, 280 ms live debounce, and full dark mode.

BitDownToc, the closest dedicated competitor, provides a solid TOC generator with platform presets (GitHub, GitLab, Hashnode, dev.to) and a [TOC] insertion marker, but it only handles Latin-script text — Cyrillic, CJK, Arabic, and Devanagari headings produce broken slugs. ToolsSonic uses the Unicode property escapes \p{L}\p{N} to keep all script characters, making it the correct choice for international documentation teams. BitDownToc also lacks depth filtering, hierarchical numbering, {#id} support, a heading map, and session history. StackEdit and Dillinger are full cloud editors — not dedicated TOC generators — and both require cloud sync. ToolsSonic is entirely browser-local.

Slug Algorithm Reference

Heading text	GitHub-like slug	Clean ASCII slug
`## Getting Started`	`#getting-started`	`#getting-started`
`## C++ API Reference`	`#c-api-reference`	`#c-api-reference`
`## Настройка сервера`	`#настройка-сервера`	`#-`
`## 安装指南`	`#安装指南`	`#-`
`## FAQ` (first)	`#faq`	`#faq`
`## FAQ` (second)	`#faq-2`	`#faq-2`
`## Install {#install}`	`#install` (explicit)	`#install` (explicit)

ToolsSonic vs Competing TOC Generators

Feature	ToolsSonic	BitDownToc	StackEdit	Dillinger
ATX + Setext headings	✅	✅	✅	✅
Fenced-code exclusion	✅	✅	—	—
Unicode slug support	✅ (all scripts)	⚠️ Latin only	—	—
Depth filter (H1–H6)	✅	—	—	—
Hierarchical numbering	✅	—	—	—
Explicit {#id} anchors	✅	—	—	—
Duplicate disambiguation	✅	✅	—	—
Heading Map + source lines	✅	—	—	—
Open local .md file	✅	—	✅	✅
Session history	✅ 8 entries	—	—	—
100% browser-local	✅	✅	❌ cloud sync	❌ cloud sync
Dark mode	✅	—	✅	✅

100% private — runs in your browser Instant — no server round-trip Free forever — no account needed

Markdown Formatter

Editor's choice

Format Markdown locally with consistent headings, lists, blank lines, blockquotes, tables, code fences, GFM task lists, strikethrough, diagnostics, history, preview, copy, and download.