What is a table of contents in Markdown?

A Markdown TOC is a list of links to the headings in a document. Each link uses a fragment identifier (#slug) that matches the heading's anchor. When rendered in GitHub, GitLab, or a static site generator, clicking a TOC entry jumps to that section.

What is the difference between GitHub and GitLab slug styles?

Both lowercase the heading text and replace spaces with hyphens. GitHub strips most punctuation; GitLab is slightly more permissive. MkDocs uses a similar algorithm but handles underscores differently. If your TOC links are broken, try switching the slug style to match your platform.

How are duplicate headings handled?

When the same heading text appears more than once, a numeric suffix is appended to make the slug unique: #introduction, #introduction-1, #introduction-2. This matches the behaviour of GitHub and most other renderers.

Does the tool handle headings inside code blocks?

Yes. The parser tracks fenced code blocks (triple-backtick and triple-tilde) and skips any lines inside them. A line like "# not a heading" inside a code block will not appear in the TOC.

Can I filter which heading levels appear in the TOC?

Yes — use the Min level and Max level controls. Setting min=2 and max=3 includes only H2 and H3 headings, which is the most common choice for documentation sites.

Markdown TOC Generator

Generate a markdown TOC from your headings with GitHub, GitLab, or MkDocs slug style.

Slug style

Min level

Max level

Markdown input

7 heading(s) detected

- [Installation](#installation)
  - [From npm](#from-npm)
  - [From source](#from-source)
- [Configuration](#configuration)
  - [Environment variables](#environment-variables)
  - [Config file](#config-file)
- [Troubleshooting](#troubleshooting)

About Markdown TOC Generator

Generate a markdown table of contents from your headings with GitHub, GitLab, or MkDocs slug styles. Handles fenced code blocks, duplicate headings, inline formatting in heading text, and level filtering. Output is available as Markdown or HTML.

Pipeline

Markdown Preview — preview the document with the generated TOC inserted.
Text Diff — compare TOC output between two versions of a document.

Frequently asked

What is a table of contents in Markdown?: A Markdown TOC is a list of links to the headings in a document. Each link uses a fragment identifier (#slug) that matches the heading's anchor. When rendered in GitHub, GitLab, or a static site generator, clicking a TOC entry jumps to that section.
What is the difference between GitHub and GitLab slug styles?: Both lowercase the heading text and replace spaces with hyphens. GitHub strips most punctuation; GitLab is slightly more permissive. MkDocs uses a similar algorithm but handles underscores differently. If your TOC links are broken, try switching the slug style to match your platform.
How are duplicate headings handled?: When the same heading text appears more than once, a numeric suffix is appended to make the slug unique: #introduction, #introduction-1, #introduction-2. This matches the behaviour of GitHub and most other renderers.
Does the tool handle headings inside code blocks?: Yes. The parser tracks fenced code blocks (triple-backtick and triple-tilde) and skips any lines inside them. A line like "# not a heading" inside a code block will not appear in the TOC.
Can I filter which heading levels appear in the TOC?: Yes — use the Min level and Max level controls. Setting min=2 and max=3 includes only H2 and H3 headings, which is the most common choice for documentation sites.