How do GitHub anchor slugs work?

GitHub converts each heading to a URL anchor by: (1) lowercasing the text; (2) removing accents and non-ASCII characters via Unicode normalization; (3) replacing whitespace runs with a single hyphen; (4) dropping every character that is not a-z, 0-9, hyphen, or underscore. So "Getting Started" becomes "getting-started" and "What's New in 2026?" becomes "whats-new-in-2026". Duplicate slugs within the same document get suffixed: "Installation", "Installation-1", "Installation-2". Our tool implements this algorithm exactly for the GitHub option.

How is GitLab slugification different from GitHub?

GitLab is slightly stricter: any run of non-alphanumeric characters becomes a single hyphen (so two consecutive symbols collapse), then leading/trailing hyphens are trimmed. GitHub preserves underscores, GitLab collapses them. Practical difference: "node_modules" stays "node_modules" on GitHub but becomes "node-modules" on GitLab. Pick the platform where your document will actually be rendered — anchor links break silently if you pick the wrong style.

Does the generator handle headings inside code blocks?

No — fenced code blocks (``` or ~~~) are skipped. Otherwise a line like # in a Bash sample would be misinterpreted as an H1. The state machine tracks code-fence open/close markers and only counts headings outside fences. Inline backticks (single-line code) do not affect heading detection — only fenced blocks.

What if my document has duplicate headings?

Both GitHub and GitLab suffix duplicates with incrementing numbers. The first "Installation" gets slug "installation", the second gets "installation-1", the third "installation-2", and so on. Our tool follows this convention. The TOC links jump to the correct heading because each heading gets the same anchor when the document is rendered. If you want unique anchors, just use unique heading text.

How is "base level normalization" useful?

If your document starts at H2 (because H1 is reserved for the page title in your CMS), the TOC indentation should treat H2 as the top level, not be indented one level deep. We auto-detect the smallest heading level used among the filtered headings and start the TOC at that level's indentation depth = 0. The depth of nested headings is then relative. This produces clean, properly-aligned output regardless of where your document starts in the heading hierarchy.

Why might I want a TOC without anchor links?

For plain-text documents (CHANGELOG.md printouts, code review summaries, email replies) the [text](#slug) syntax adds visual noise and the links do not work. Untoggle "Include #anchors" to get a simple indented list of heading text only. Useful for AGENTS.md files, internal-tool readmes, and any context where the TOC is for orientation rather than navigation.

How does this differ from your Markdown Editor?

Markdown Editor is a writing tool with live preview — useful while authoring. TOC Generator is a one-shot extractor — useful when the document is already written and you want a table of contents at the top. The natural workflow: write in the editor, paste the final draft here to extract the TOC, paste the TOC back at the top of the document, repeat as you add headings. Some CMS platforms auto-generate TOCs at render time; this tool is for when they do not.

Can I limit the TOC to top-level headings only?

Yes — set both Min Level and Max Level to the same value (e.g. both H2) to get a flat TOC containing only that level. Or set Min=H1, Max=H2 to skip H3+ for a cleaner high-level overview. The most common pattern for long documents is Min=H1, Max=H3 — captures structure without drowning in leaf-level subheadings.

Are my Markdown documents sent to any server?

No. The parser walks your input via JavaScript inside the browser tab; the output is constructed in memory. There is no fetch, no XHR, no analytics event with document content. Drafts, internal notes, and confidential design docs stay on your device. Verify in DevTools → Network — no requests fire during a TOC generation.

Free Markdown Table of Contents Generator (GitHub / GitLab / Pandoc Anchors)

Paste any Markdown document and get a clean linked table of contents using GitHub-, GitLab-, or Pandoc-style heading slugs. Configurable heading depth, indented nesting, ordered or unordered list, with duplicate-slug suffixes handled automatically.

Min levelMax levelSlug styleIndentNumbered listInclude #anchors

Markdown input(14 total headings, 14 included)

Table of contents

- [Toolk Project Documentation](#toolk-project-documentation)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Installation](#installation)
    - [First Run](#first-run)
  - [Architecture](#architecture)
    - [Frontend Stack](#frontend-stack)
    - [Component Library](#component-library)
      - [Color Tokens](#color-tokens)
      - [Typography](#typography)
  - [Contributing](#contributing)
    - [Code Style](#code-style)
    - [Pull Requests](#pull-requests)
  - [License](#license)

Auto-Indented Nesting

Each heading depth (#, ##, ###) becomes one level deeper in the list output. Base level is normalized so the TOC starts flush regardless of the source's top heading.

Three Slug Styles

GitHub (default), GitLab, and Pandoc — pick the platform where the document will be rendered. Duplicate slugs auto-suffix with -1, -2, -3 (the GitHub convention).

Configurable Depth

Restrict to top-N levels (e.g. include only H1-H3 and skip the leaf-level sub-headings). Choose ordered (numbered) or unordered list output, 2 or 4 space indent.

100% Client-Side

Markdown documents may contain drafts, internal notes, or sensitive prose. The parser runs entirely in your browser — nothing leaves the page.

Anchors That Actually Work, On Every Platform

Every Markdown renderer auto-generates anchor IDs for headings, but the slugification rules vary by platform — GitHub keeps underscores, GitLab collapses them, Pandoc follows yet another convention. Hand-writing a TOC and guessing the slugs breaks half the links. Our Free Markdown TOC Generator applies the exact platform rule to each heading you have in the source, handles duplicate-slug suffixing automatically, and emits clean indented Markdown ready to paste at the top of your README or documentation page.

Pair this with our Markdown Editor (live writing tool), Markdown to HTML (one-shot conversion when you ship to non-Markdown systems), Markdown Table Generator (visual table-shaped Markdown builder), and the URL Slug Generator (sibling tool for non-heading URL slugs).

How Each Platform Slugifies Headings

Platform	Slug Rule	Notes
GitHub	lowercase → replace whitespace with hyphens → drop everything except [a-z0-9-_]	Used by README anchors on github.com. Most permissive about underscores.
GitLab	lowercase → replace any non-alphanumeric run with single hyphen → trim hyphens	GitLab pages and wiki anchors. Stricter — collapses runs of punctuation.
Pandoc	Same as GitHub for common cases	Used by Pandoc-rendered HTML and many static-site generators.

Where TOC Generation Helps

README and documentation

GitHub renders Markdown READMEs with auto-anchored headings — paste your draft and generate the TOC to put at the top.

Blog posts

Long-form posts benefit from a TOC for scannability. Generate one quickly from your draft headings.

Technical specifications

RFC-style specs and design docs need a TOC. Generating it deterministically prevents drift between body and TOC.

Wiki pages

GitLab and Confluence wikis use slug-based anchors. Pick the right slug style for your platform.

Documentation sites

Static-site generators (Docusaurus, MkDocs, VitePress) can auto-generate TOCs at build time, but a generator helps when porting drafts.

Four TOC Authoring Tips

1. Stop at H3 for Most Documents

H4 and deeper rarely belong in a top-level TOC. The signal-to-noise tips against you. Set Max Level to H3 for blogs, H4 for long technical specs.

2. Keep Headings Concise

Long headings produce long slugs and ugly anchor URLs. Aim for 2-6 words per heading. Move detail to the heading's body text.

3. Avoid Duplicate Heading Text

Duplicates auto-suffix with -1, -2, etc. which produces fragile anchors (the link target shifts when you insert/remove sections). Make heading text unique.

4. Regenerate After Big Edits

If you reshuffle sections, the TOC at the top drifts. Re-paste the document here and re-extract — takes 5 seconds and prevents broken anchors.

Related Markdown & Content Utilities

Markdown Editor

Live writing tool with split preview

Markdown to HTML

One-shot batch conversion

Markdown Table

Visual table builder

URL Slug Generator

Non-heading URL slugs