Table of Contents Generator

A good README or long doc deserves a table of contents. Scrolling a 3,000-line markdown file to find section 17 is no one's idea of fun, and adding a TOC at the top shrinks navigation to a single click. But maintaining a TOC manually is a recipe for staleness — you add a heading and forget to update the TOC, rename a section and the anchor links break. This generator reads your markdown (or HTML), extracts the headings, and outputs a clean nested TOC with working anchor links in one step.

The generator understands how GitHub and most static site generators produce anchor IDs. It slugifies heading text the same way — lowercase, spaces to dashes, punctuation stripped — so the links you generate here actually work on the rendered page. You can override the slugify rules if your target platform uses a different convention (MkDocs, Docusaurus, Hugo, Jekyll all differ slightly).

Depth is configurable. Include only H1 and H2 for a high-level summary, or go all the way to H6 for deeply nested docs. Numbering can be off (plain bullet list), decimal (1.1, 1.2, 1.2.1), or fully nested with custom prefixes. The output is markdown bullet list by default with anchor links, but you can switch to HTML <ul> for sites that need inline HTML or to plain text for emails and notes. Whatever you pick, re-run the generator when you add sections and paste the updated TOC back in — a 10-second maintenance task instead of a fiddly manual edit.

Markdown headings use #, ##, up to ###### to indicate H1 through H6. The generator scans the document for these prefixes (skipping over code blocks where # means a Python comment or shell script prompt) and builds a tree based on the hierarchy it finds. HTML inputs are parsed using the same hierarchy via <h1> through <h6> tags.

Anchor generation follows GitHub conventions by default: lowercase the heading, replace spaces with dashes, strip most punctuation, and append numeric suffixes when duplicate headings would collide. This matches GitHub's README rendering and is compatible with GitLab and most markdown-to-HTML renderers. Options exist for MkDocs Material (which uses underscores in some cases), Docusaurus (which allows explicit {#custom-id} attributes), Hugo (which uses Blackfriday's slug rules), and Jekyll (Kramdown).

The TOC output can be:
- Markdown bullet list with heading links (most common)
- Markdown ordered list with numbering preserved
- HTML <ul>/<ol> with <a href="#slug"> elements
- Plain text with indentation and no links (for emails and notes)

Depth is controlled by min-depth and max-depth settings. If your document starts with an H1 title and you want the TOC to skip it, set min-depth to 2. If you only want a top-level summary, set max-depth to 2 or 3. The tool also supports excluding specific headings by name or by a marker in the heading text (e.g., ## Section {no-toc}).

Manual TOC maintenance is tedious and quickly goes stale. Tools like doctoc, markdown-toc, or npm packages work but require installation and setup. IDE plugins exist but lock you into one editor. Static site generators often build TOCs automatically for rendered pages, but many markdown hosts (GitHub, GitLab, internal wikis) show only what you put in the source file. This tool handles the full pipeline in the browser: input in markdown or HTML, pick a slug style matching your renderer, get a clean TOC with working anchor links, and paste back. Fast, accurate, and framework-aware.