Home › Developer Tools › Markdown TOC Generator
Markdown TOC Generator
Paste your README or any Markdown file and get a nested, linked table of contents built from its headings. Anchors follow GitHub's or GitLab's rules (duplicates included), so every link jumps to the right section, and you can insert the TOC straight into the document.
Last updated:
Advertisement
Advertisement
How to use the Markdown TOC Generator
- Paste your Markdown or open a .md file. A sample README is loaded so you can see the result right away.
- Choose the heading levels to include. Many READMEs skip the H1 title and list H2 and H3 sections.
- Pick the anchor rules for where the file will be shown (GitHub or GitLab) and the bullet and indent style.
- Copy the TOC and paste it under your title, or use Insert into document to add it between <!-- toc --> markers.
- Regenerate any time: paste the updated file and insert again; the old TOC between the markers is replaced.
How heading anchors are generated
Both GitHub and GitLab turn the visible text of a heading into an id you can link to with #anchor. The steps are:
- Take the rendered text only:
**bold**,[links](url)and inline HTML are reduced to their text, images disappear, and`code`keeps its content. - Convert to lower case.
- Remove punctuation and symbols. Letters (including accented and non-Latin letters), digits, spaces, hyphens and underscores stay.
- Replace every space with a hyphen. GitLab also collapses repeated hyphens into one.
- If the anchor already exists earlier in the document, add
-1,-2, … in order.
| Heading | GitHub anchor | GitLab anchor |
|---|---|---|
## Getting Started | #getting-started | #getting-started |
## What's New in v2.0? | #whats-new-in-v20 | #whats-new-in-v20 |
## Options & Flags | #options--flags | #options-flags |
## Config file (`.acmerc`) | #config-file-acmerc | #config-file-acmerc |
## snake_case_names | #snake_case_names | #snake_case_names |
## Usage (second time) | #usage-1 | #usage-1 |
## Café Menü | #café-menü | #café-menü |
Tips for a good README table of contents
- Skip the H1. The title is already at the top of the page, so most TOCs start at H2. Going deeper than H3 usually makes the list too long to scan.
- Don't skip levels. Jumping from H2 straight to H4 breaks the outline; the generator still nests the entry under its nearest parent and warns you.
- Numbered TOCs need wider indents. In CommonMark a nested item must line up with the text after
1., so numbered lists are indented at least 3 spaces even if 2 is selected. - Use the markers.
<!-- toc -->and<!-- tocstop -->are the same markers used by the popular markdown-toc CLI, so the generated block can also be refreshed by that tool in a pre-commit hook. - Renaming a heading changes its anchor and breaks links from other pages. Regenerate the TOC after edits and check external links.
Writing the README itself? Start with the README Generator, and format data with the Markdown Table Generator.
Frequently asked questions
How does GitHub create heading anchors?
GitHub takes the heading's text, converts it to lower case, removes punctuation and symbols (letters, numbers, spaces, hyphens and underscores are kept), and replaces each space with a hyphen. So ## What's New? becomes #whats-new. Formatting such as bold or links is removed first and only the visible text is used.
What happens with duplicate headings?
The first heading keeps the plain anchor and later ones get -1, -2 and so on. Two sections called Usage become #usage and #usage-1. The generator numbers duplicates in document order, exactly as GitHub and GitLab do.
Are GitLab anchors different from GitHub's?
Mostly the same, with one practical difference: GitLab collapses runs of hyphens into one, so A - B becomes #a-b on GitLab but #a---b on GitHub. Pick the GitLab option if your README is hosted there.
Why are some headings missing from my TOC?
Lines starting with # inside fenced code blocks (``` or ~~~) are code, not headings, so they are skipped. Headings outside the selected depth range are left out, and a # must be followed by a space to count as a heading in CommonMark.
How do I keep the table of contents up to date?
Insert the TOC with the markers <!-- toc --> and <!-- tocstop -->. Next time, paste the edited file and click Insert into document again: everything between the markers is replaced with a fresh TOC. The markers are HTML comments, so they are invisible on GitHub.
Does GitHub generate a table of contents automatically?
GitHub shows an outline menu for README and Markdown files in the file viewer, but it does not add a TOC to the rendered page itself. Writing a TOC into the file makes it visible on the page, on npm, in editors and in exported documents.
Are all the tools on FreeToolCabin tested for quality and accuracy?
Yes! Every tool on our site undergoes automated Q/A testing in real browser environments to ensure high precision, correct output, and zero errors. If you happen to spot a bug or have a suggestion, please contact us at [email protected] and our team will review it right away.
Related tools
README GeneratorFill in a form and get a polished README.md with badges, install, usage and license, live preview.Markdown EditorWrite Markdown with a toolbar, live split preview, autosave and .md or HTML export.Markdown Table GeneratorBuild Markdown tables in a grid or paste from Excel/CSV, with alignment and preview.Markdown Cheat SheetInteractive Markdown syntax reference: edit every example and see the live rendered preview.Online OutlinerBullet outliner with collapse, drag reorder, Tab indent and Markdown, OPML or TXT export.QR Code GeneratorMake QR codes for links, Wi-Fi, email and more.Barcode GeneratorCreate Code 128, EAN-13, UPC-A, EAN-8, Code 39 and ITF-14 barcodes as PNG or SVG.UUID GeneratorGenerate UUID v4 and v7 / GUIDs in bulk and copy or download them.Schema Markup Generator (JSON-LD)Create JSON-LD structured data for FAQ, Product, Article and more.Htaccess & Nginx Redirect GeneratorBuild 301 redirects for .htaccess, Nginx and Netlify or Cloudflare _redirects.Fake Data GeneratorGenerate mock data as JSON, CSV or SQL.Random String GeneratorGenerate secure random strings and tokens in bulk with any length and character set.API Key GeneratorCreate secure API keys and secrets with prefixes, checksums and SHA-256 hashes for storage.MIME Type LookupFind the MIME type for any file extension, or the extensions for a MIME type, in 400+ entries.Cron Expression GeneratorBuild crontab schedules visually, read them in plain English and see the next run times.URL Slug GeneratorTurn titles into clean, SEO-friendly URL slugs: accents, stop words, separators and bulk lines.JSON Schema GeneratorTurn sample JSON into a draft 2020-12 JSON Schema with types, required fields and formats.Gitignore GeneratorBuild a .gitignore from 50+ templates for languages, frameworks, IDEs and OS, merged and deduped.License GeneratorCreate a LICENSE file for MIT, Apache, GPL, BSD, ISC, MPL or Unlicense with your name and year.ULID GeneratorGenerate sortable ULIDs and UUID v7 in bulk, monotonic option, and decode their timestamps.Htpasswd GeneratorCreate .htpasswd entries with bcrypt, APR1-MD5 or SHA-1 for Apache and Nginx basic auth.Placeholder Image GeneratorCreate placeholder images in any size, color and text as PNG, JPG, WebP, SVG or data URI.Ads.txt GeneratorCreate or validate ads.txt and app-ads.txt files: seller lines, cert IDs and variables.Docker Run to Compose ConverterConvert docker run commands to docker-compose.yml, or a compose file back to docker run.Dockerfile GeneratorGenerate a production Dockerfile and .dockerignore for Node, Python, Go or a static nginx site.HTML Boilerplate GeneratorTick the options you need and get a clean HTML5 starter template with meta, OG tags and CSS reset.JSON to Zod SchemaInfer a Zod (or Yup) schema from sample JSON with optional, nullable and z.infer types.Linux Commands Cheat SheetSearchable Linux and bash command reference with flags explained, examples and copy buttons.LLMs.txt GeneratorBuild an llms.txt file for AI crawlers: summary and link sections, import from your sitemap.Nano ID GeneratorGenerate secure Nano IDs with custom alphabet, length and count, plus a collision calculator.Nginx Config GeneratorBuild an nginx server block: static site, SPA, reverse proxy or PHP, with SSL, gzip and redirects.OpenAPI / Swagger ViewerView OpenAPI 2/3 JSON or YAML as interactive API docs with validation and an endpoint list.package.json GeneratorFill a form and get a valid, npm-ready package.json with scripts, dependencies and checks.PKCE Code Challenge GeneratorGenerate an OAuth 2.0 PKCE code_verifier and S256 code_challenge, build auth URLs, verify pairs.Regex GeneratorBuild regular expressions visually from blocks or presets (email, date, phone) and test them live.Commit Message GeneratorBuild Conventional Commit messages with type, scope, body, breaking change and issue refs.Database Schema DesignerDesign tables and relationships visually, then export SQL for MySQL, PostgreSQL or SQLite.Docker Compose GeneratorBuild a docker-compose.yml with a form: services, ports, volumes, env, healthchecks and presets.Dockerfile LinterLint a Dockerfile for best practices: pinned tags, apt cleanup, non-root USER and layer count.Dockerignore GeneratorBuild a .dockerignore from Node, Python, Go and Java templates, plus your own entries.ESLint Config GeneratorGenerate a flat eslint.config.js for JavaScript, TypeScript, React or Node with rule presets.Git Branch Name GeneratorTurn a ticket ID and title into a clean, valid git branch name like feature/PROJ-12-add-login.GitLab CI Config GeneratorGenerate a .gitlab-ci.yml with stages, jobs, images, cache, artifacts and rules from templates.Jinja2 Template TesterRender Jinja2 templates with YAML or JSON variables using real Jinja2, with clear error lines.JSON Schema Mock Data GeneratorGenerate realistic sample JSON from a JSON Schema: formats, patterns, $ref, seeds and counts.Kubernetes Secret GeneratorCreate Kubernetes Secret YAML from key/value pairs or .env with auto base64, or decode one.Kubernetes YAML ValidatorValidate Kubernetes manifests against the API schema of a chosen version, with error paths.Prettier Config GeneratorToggle Prettier options, preview formatted code live and copy your .prettierrc file.Quartz Cron GeneratorBuild and explain Quartz and Spring cron expressions with seconds, ?, L, W and #, plus next fire times.README Badge GeneratorCreate Shields.io-style README badges for license, version, build and custom labels.Systemd Service File GeneratorCreate a systemd .service unit with ExecStart, user, restart policy, environment and hardening.tsconfig.json GeneratorBuild a tsconfig.json with target, module, strict checks and path aliases, each option explained.Access Log AnalyzerAnalyze Apache and Nginx access logs: top URLs, IPs, status codes, bots and traffic charts.Regex String GeneratorGenerate random test strings that match any regular expression, checked against the real regex.ASCII Table GeneratorTurn CSV or pasted cells into plain-text tables: MySQL, Markdown, Unicode box and reST styles.Dummy File GeneratorCreate test files of an exact size in KB, MB or GB with zeros, random bytes or text.FFmpeg Command GeneratorPick a task and options, get the exact ffmpeg command with every flag explained.Folder Tree GeneratorTurn a local folder or an indented list into an ASCII directory tree for your README.GitHub Actions Workflow GeneratorBuild a GitHub Actions CI workflow: triggers, matrix, caching, tests, Pages or Docker deploy.Kubernetes YAML GeneratorGenerate Deployment, Service, Ingress, ConfigMap, Secret and HPA manifests with safe defaults.OpenAPI EditorEdit OpenAPI/Swagger YAML or JSON side by side with live API docs, validation and download.OpenAPI ValidatorValidate OpenAPI 3.0/3.1 and Swagger 2.0 specs: schema errors, broken $refs, line numbers.Pivot Table MakerBuild pivot tables from CSV or Excel by drag and drop: sum, count, average, charts, export.SQL Query BuilderBuild SELECT queries visually: joins, filters, GROUP BY, ORDER BY and LIMIT, as clean SQL.Truth Table GeneratorType a logic expression and get its full truth table, minterms and canonical DNF/CNF.TypeScript PlaygroundWrite TypeScript with live type checking, see the compiled JavaScript and run it in your browser.Article Schema GeneratorCreate Article, BlogPosting or NewsArticle JSON-LD with headline, authors, dates and images.Event Schema GeneratorCreate Event JSON-LD with dates, venue or online location, tickets, organizer and performers.