Skip to content
Markdown Viewer

Markdown TOC Generator

Generate a Markdown table of contents — configurable, auto-injecting

Build a clean, GitHub-compatible TOC for any README, blog post, or docs page. Choose heading depth, bullet style, indent, and ordered vs unordered. Inject between<!-- TOC --> markers for repeatable updates.

Single-heading slugsHeading auditSlug collisions

If your README already has <!-- TOC --> and <!-- /TOC --> markers, the TOC is replaced between them; otherwise it is prepended to the top of the document.

How to use the Markdown TOC generator

  1. Paste Markdown into the source pane, or open a .md file.
  2. Pick a level range — H2 to H4 is the standard sweet spot for READMEs and docs pages.
  3. Choose a style: ordered (1.) or unordered with your preferred bullet (-, *, or +).
  4. Choose indent: 2-space (Prettier default) or 4-space.
  5. Copy the TOC — or copy the document with injected TOC if your source already has <!-- TOC --> / <!-- /TOC --> markers.

Why a TOC matters

  • Discoverability. GitHub renders the top of your README in search previews and on the repo home. A TOC tells visitors what's inside in 5 seconds.
  • Long-doc navigation. Tutorials and API references quickly grow past one screen. A clickable TOC saves scrolling.
  • Anchor reuse. Once you have anchors, you can link to specific sections from chat, social, or other docs.
  • Static-site sidebars. Many docs frameworks (Docusaurus, MkDocs, Nextra) derive their right-sidebar nav from heading IDs identical to the ones used here.

Workflow: keep your README TOC fresh

# My library

<!-- TOC -->
<!-- /TOC -->

## Installation
…

Before each release:

  1. Paste your README here.
  2. Copy the "document with injected TOC".
  3. Commit. Done.

The injection is idempotent — re-running won't duplicate the TOC, and it preserves everything outside the markers.

Tips for high-quality TOCs

  • Don't include H1. The TOC sits below your H1 title; including it duplicates the heading.
  • Cap at H3 or H4 for READMEs. Deeper TOCs become noise. Save deeper levels for API references.
  • Use ordered TOCs in long-form essays, unordered in technical docs.
  • Pair with the Heading Auditor. A clean hierarchy produces a clean TOC.

Companion tools

Privacy & data

All processing happens inside your browser. We don't upload, log, or store the Markdown you paste.

Frequently asked questions

How do I generate a Markdown table of contents?
Paste your Markdown, pick the minimum and maximum heading levels you want listed (typically H2–H4), choose list style (ordered or unordered), and copy the TOC. The generator builds GitHub-compatible anchor links from each heading.
Can it auto-update the TOC inside an existing README?
Yes. Add the markers `<!-- TOC -->` and `<!-- /TOC -->` to your README. When you copy the 'document with injected TOC', the generator replaces whatever is between those markers with the fresh TOC. Future runs are idempotent.
What slug algorithm does it use?
GitHub-style: lowercase, strip non-word characters, collapse whitespace into hyphens, dedupe with `-1`, `-2` suffixes for duplicate headings within the same document. This matches what GitHub, Docusaurus, MkDocs, and most static-site generators do.
Can I get an ordered (numbered) TOC?
Yes — switch the List style dropdown to Ordered. Each line becomes `1.` which renders correctly numbered on GitHub and most renderers (they auto-increment regardless of the literal digit used in source).
Is there a separate tool for raw slugs only?
Yes — see the [Markdown Slug Generator](/tools/markdown-slug-generator). The slug generator is best for one-off ID lookup; this page is best when you need a complete, configurable TOC with depth limits and injection support.
Is my Markdown uploaded?
No. Slug derivation, depth filtering, and injection all run inside your browser tab. We don't upload, log, or store any content.