Markdown Table of Contents Generator

What this generator produces

Markdown Table of Contents Generator reads a Markdown document, finds its headings, and writes a nested bullet list of links that point at each heading's anchor. The output is a plain Markdown block you can paste near the top of a README, a docs page or a long article.

For a document like this:

# Project
## Installation
### Requirements
## Usage

the result is:

- [Project](#project)
  - [Installation](#installation)
    - [Requirements](#requirements)
  - [Usage](#usage)

Each entry uses the heading text as the visible label and a lowercased, hyphenated version of that text as the anchor. Indentation follows the heading depth.

How headings are detected

The scanner reads the document line by line and matches ATX headings: one to six # characters at the start of a line, followed by a space and some text. Lines inside fenced code blocks are skipped, so a shell comment beginning with # inside a snippet is not turned into a table-of-contents entry. Fences are recognised from three or more backticks or tildes, and the closing fence must use the same character as the opening one.

Two consequences follow from that rule. Setext headings, written with a line of === or --- under the text, are not recognised at all. And a document that opens with YAML front matter is not protected: a comment line such as # Site title inside the front matter looks exactly like an H1 to the scanner and is included in the output. If your file starts with front matter, remove the comment lines before generating, or delete that first entry afterwards.

How the anchor is built

Anchors are generated by lowercasing the heading text, deleting everything that is not a letter, a number, a space or a hyphen, replacing runs of whitespace with a single hyphen, collapsing repeated hyphens, and trimming hyphens from both ends. Accented letters and non-Latin scripts are kept, so a heading in Hindi or Greek produces a readable slug rather than an empty one. Punctuation such as commas, colons, question marks, full stops and parentheses is removed.

Examples of the transformation:

• ## Getting Started becomes #getting-started
• ## API: Errors & Retries becomes #api-errors--retries, with the ampersand removed and its surrounding spaces turned into hyphens
• ## Héllo Wörld! becomes #héllo-wörld
• ## Step 1 — Install becomes #step-1--install, since the em dash is stripped but the spaces around it remain

That dash behaviour is worth knowing: removing a symbol does not remove the spaces that surrounded it, so headings with punctuation often end up with two hyphens in a row. The link is still valid for the platform's own slugger in most cases, but it can look untidy in the generated file.

Indentation and depth

Indentation is two spaces per level, measured relative to the shallowest heading in the document rather than absolutely. If a document's top heading is H2, the H2 entries sit at the left margin and H3 entries are indented one step; the H1 level is not reserved. This keeps the output compact for documents that start below H1, but it also means the same heading level can land at different indentation in two files with different structures.

The shallowest level is calculated across the whole document, not discovered as the scanner moves down. A document that ends with an H1 after a series of H2 sections will therefore indent all the H2 entries, even though the H1 arrives last. Order is preserved exactly as the headings appear.

Using the tool

1. Paste the Markdown into the input editor. The footer shows the character count and a live heading count based on a quick pattern match.
2. Press Generate. The request is sent to the server and the table of contents comes back as text.
3. Read the output panel. It is read-only, so the result cannot be edited in place; copy it and edit elsewhere if you need changes.
4. Use Copy to put the block on the clipboard, or Download to save it as markdown-toc.md.
5. Paste the block at the top of your document, under the title, and add a heading such as ## Contents above it if you want one.
6. Press the trash icon to clear both panels and start again.

If the document contains no ATX headings, the output is empty and the page reports that no headings were found rather than producing a broken list.

Where it is useful

• README files. A long project README benefits from a linked outline at the top.
• Documentation pages. Static site generators often require a manual list of anchors in the page body or in front matter.
• Long-form articles. Give readers a way to jump to a section without scrolling.
• Release notes. Link to each version's section when one page collects many releases.
• Handover notes. A structured index makes a runbook easier to navigate.

The generated anchors are designed to match GitHub-style slugging, which is also used by many other Markdown renderers. They are not guaranteed to match every static site generator: MkDocs, Docusaurus, GitBook and Hugo each have their own anchor rules, and some of them keep punctuation or add prefixes. Check one generated link against the rendered page before relying on the whole list.

Known quirks to check

The generator is a practical line scanner, and a few cases produce output you should review:

• Duplicate headings. Two headings with the same text receive the same anchor. GitHub disambiguates them with -1, -2 and so on, so the second link in the list will point at the first section. Rename one heading or fix the anchor by hand.
• Closing hashes. A heading written as ## Title ## keeps the trailing hashes in the link label, producing [Title ##](#title). The anchor is correct; the label looks odd.
• Links inside headings. A heading such as ## [Setup](https://example.com) is kept as raw text, so the generated line nests a link inside a link and the anchor absorbs the URL. Avoid links in headings, or edit the entry afterwards.
• Inline code in headings. Backticks stay in the label but are stripped from the anchor, so ## `code()` becomes a code-formatted label pointing at #code. That usually renders well.
• Emoji and symbols. Emoji are removed with other punctuation, which can collapse two different headings to the same slug.
• Front matter comments. As described above, # comment lines in YAML front matter are treated as headings.

Limits

Input is limited to 200,000 characters per request and larger documents are rejected with a validation error. The generation is server-side, so the Markdown is sent with the request rather than processed in the browser. The tool does not render a preview, does not rewrite the document, does not insert the table of contents for you, and does not renumber or reorder headings. It produces the block and nothing else.

Privacy

Because the request goes to the server, avoid pasting unpublished drafts, private repository contents or anything confidential. No account is required, the response contains only the generated list, and the document is not stored as a saved project. If the content is sensitive, generate the table of contents after removing the body text — the headings alone are enough.

Common mistakes

• Expecting setext headings to appear. Only hash-style headings are read.
• Pasting a file with front matter. Comment lines there become entries.
• Assuming anchors match your site generator. Verify against the rendered page.
• Leaving duplicate headings. The second link will jump to the first occurrence.
• Forgetting to add a “Contents” heading. The block is just a list; it needs a label if you want one.
• Editing the read-only output panel. Copy it first, then edit.

Frequently Asked Questions