Markdown TOC Generator: Build a Table of Contents

How to use the markdown toc generator

1. Paste your Markdown document into the Markdown source text area.
2. Choose between a nested indented list or a flat list for the output format.
3. Set the Max heading depth to filter out lower-level headings you do not want in the table of contents.
4. Check Render HTML preview if you also need the full document converted to safe HTML.
5. Copy the generated TOC from the output area and paste it directly into your Markdown file.

How the slug generation works

A markdown toc generator needs to turn heading text into URL-safe anchor links. The process follows the GitHub rule: take the plain text of the heading (inline formatting removed), convert it to lowercase, delete punctuation except hyphens and underscores, and turn each space into a hyphen. Letters from any alphabet are kept, so Café becomes café. For example, the heading ## Getting **Started** Fast! becomes the text "Getting Started Fast!", which produces the slug #getting-started-fast.

Punctuation characters like exclamation marks, commas, and periods are removed entirely, and the spaces around a removed character stay, so a heading such as C++ & more! becomes c--more and a - b becomes a---b, exactly as GitHub does it. If two headings produce the same slug, a numeric suffix is appended. The first duplicate gets -1, the second -2, and so on. This matches the behavior of GitHub, GitLab, and most static site generators.

Supported Markdown subset

Headings are found with the same Markdown parser the other converters on this site use, so setext headings (underlined with === or ---), tildes fences, headings inside quotes or list items, and closing # marks are all handled. When you enable the HTML preview, the document is rendered with CommonMark rules plus GitHub-style tables, strikethrough and task lists. When you enable the HTML preview, the following elements are parsed and rendered safely:

• Headings: ATX style (# H1 through ###### H6)
• Emphasis and strong: *italic*, _italic_, **bold**, __bold__
• Inline code: backtick delimited `code`
• Fenced code blocks: triple backticks with optional language tag
• Links and images: [text](url) and ![alt](src)
• Lists: unordered (-, *, +) and ordered (1.)
• Blockquotes: lines starting with >
• Horizontal rules: three or more -, *, or _
• Tables: pipe-delimited rows with a separator line

Raw HTML tags in the input are escaped rather than passed through, and links with script schemes lose their target. This ensures the output is always safe to embed in a web page without cross-site scripting risks. If you need to convert existing HTML documents into Markdown first, use an html to markdown tool before generating your TOC.

Nested versus flat lists

The tool offers two list styles. A nested list uses two spaces of indentation per heading level relative to the shallowest heading in your document. If your document starts at ##, then ## gets zero indentation, ### gets two spaces, and #### gets four spaces.

A flat list places every heading at the root level with no indentation. Flat lists are useful when your heading hierarchy is deep but you want a compact, linear navigation menu. Both styles use standard Markdown unordered list syntax with hyphens, making them compatible with virtually every parser.

Common mistakes with Markdown TOCs

One frequent issue is placing the TOC inside a fenced code block by accident. Code blocks (fenced with backticks or tildes, or indented) are parsed literally, so headings inside them are ignored by this markdown toc generator. Make sure your headings are outside any backtick fences.

Another mistake is assuming that special characters in headings will survive slug generation. Characters like colons, parentheses, and ampersands are stripped from anchors. If you rely on exact character matching for links, test the generated slugs first. You can verify your final output using a markdown linter to catch structural issues.

Finally, remember that heading levels should be sequential. Jumping from # H1 directly to #### H4 creates awkward nesting in the TOC. Keep your document outline logical for the best results.

Using the generated TOC

Once you have copied the table of contents, paste it near the top of your Markdown file, typically right after the main title or an introductory paragraph. Most documentation platforms, including GitHub README files, GitLab wikis, and static site generators, will automatically resolve the anchor links.

If you need to distribute your document in other formats, you can convert the Markdown with the embedded TOC using tools like markdown to html for web publishing, or markdown to bbcode for forum posts. The anchor links in the TOC will only function in environments that support HTML IDs or equivalent fragment identifiers.

Worked examples