Markdown Table of Contents Generator

How to use the markdown table of contents generator

1. Paste your Markdown document.
2. Set how deep the contents should go.
3. Copy the list and paste it near the top of your document.

About this tool

The contents list is only useful if the links work, and that comes down to matching how the renderer builds heading anchors. GitHub lowercases the text, turns spaces into hyphens, drops punctuation, and appends a number to repeats — so two sections both called "Getting started" anchor as `getting-started` and `getting-started-1`. Those rules are followed here, including the numbering on duplicates, which is where hand-written contents lists usually break.

Inline formatting is stripped before the anchor is built, so a heading written as `**Bold heading**` links to `bold-heading` rather than to the asterisks.

Headings inside code fences are ignored. A `# comment` in a shell example is a comment, not a section, and including it produces a contents entry pointing at nothing.

Indentation is relative to the shallowest heading in the document, so a file that starts at h2 is not indented by a level that never appears.

Common uses

• Adding a contents list to a long README.
• Keeping documentation navigable as it grows.
• Regenerating a contents list after headings change.

Frequently asked questions

Why do my contents links not work?

Usually the anchor does not match the heading. Anchors are lowercased with spaces as hyphens and punctuation dropped, and repeated headings get a numeric suffix — this follows those rules.

How are two identical headings handled?

The first anchors normally and each repeat gets a suffix: getting-started, then getting-started-1. That matches GitHub's behaviour.

Are headings inside code blocks included?

No. A line starting with # inside a code fence is a comment, so including it would create a contents entry pointing nowhere.