06 / Markdown / markdown-toc

Markdown TOC Generator

Generate a table of contents from Markdown headings.

ReadyLocal processing
06 · Workspace

How to use

  1. 01Paste your Markdown document into the Markdown input.
  2. 02Use the From and To dropdowns (H1–H6) to choose which heading levels to include, for example H2 to H3.
  3. 03Check Numbered list for an ordered TOC, or leave it unchecked for bullet points.
  4. 04Review the result in the Table of contents panel. Nested headings are indented under their parents.
  5. 05Click Copy TOC or Download .md, then paste the TOC near the top of your document.

What is this tool?

The Markdown TOC Generator reads the headings in your document and builds a nested, linked table of contents that you can paste back in. Each entry links to the heading's anchor slug, duplicate headings get numbered suffixes, and headings inside fenced code blocks are ignored. Everything runs locally in your browser.

How heading anchors are generated

Code hosts like GitHub give each rendered heading an anchor that you can link to with #. This tool builds the slugs the same basic way: it lowercases the heading, removes punctuation and replaces spaces with hyphens. So "## Getting Started!" becomes #getting-started, and "### Is it free?" becomes #is-it-free.

Inline formatting characters (asterisks, underscores and backticks) are removed from the link text first. If two headings produce the same slug, the second gets -1, the third gets -2, and so on. For example, two "## Example" sections link to #example and #example-1.

Choosing heading levels and nesting

Most documents have a single H1 title that doesn't belong in its own table of contents, so a range of H2 to H3 is a common choice. Each level below the From level is indented by two spaces, which nests H3 entries under their H2 in the rendered list.

With Numbered list checked, every entry uses the "1." marker. Markdown renderers number ordered lists automatically, so the output displays as 1, 2, 3 and the source stays clean when you reorder sections.

What the generator skips

Lines inside fenced code blocks (``` or ~~~) are ignored, so a "# comment" in a bash snippet won't show up as a heading. Only ATX-style headings that start with one to six # characters are detected. Underlined (setext) headings using === or --- are not, and trailing closing hashes like "## Title ##" are trimmed.

Common use cases

  • Adding a table of contents to a long README.md
  • Building navigation for API docs or runbooks
  • Structuring test plans and QA reports with many sections
  • Keeping a CONTRIBUTING or onboarding guide easy to scan
  • Regenerating the TOC after reorganizing a document's headings

FAQ

How do I add a table of contents to a Markdown file?

Paste the file here, choose a heading range, copy the generated list and paste it near the top of your document. Each entry links to its heading's anchor.

Do the TOC links work on GitHub?

For most headings, yes. The slugs follow GitHub's basic rules: lowercase, punctuation removed, spaces turned into hyphens, and -1, -2 suffixes for duplicates.

Can I exclude the H1 title from the table of contents?

Yes. Set From to H2 so only H2 and deeper headings are included.

Why is a heading missing from my TOC?

It may be outside the selected From/To range, inside a fenced code block, or written in setext style (underlined with === or ---). Only # style headings are detected.

Can I generate a numbered table of contents?

Yes. Check Numbered list to output an ordered list instead of bullet points.