What is a Markdown TOC generator?
A table of contents lists a document's sections with links that jump straight to each one. Long READMEs, API docs, wikis and guides are much easier to navigate with one, but writing it by hand means working out every anchor and redoing it whenever a heading changes.
A TOC generator reads the headings in your Markdown, nests them by level and builds the anchor links automatically, in the format GitHub uses. Project maintainers use it for READMEs, technical writers for documentation, and students for long notes kept in Obsidian or similar Markdown apps.
How to use the Markdown Table of Contents Generator
1.Paste the document
A README, a guide or any Markdown with headings.
2.Choose the depth
Include headings down to H2, H3, H4 or all six levels, and leave out the title.
3.Paste the TOC in
Put it near the top of the document, usually under the introduction.
Example: a user guide
A document with the H1 "User guide", H2s Installation, Configuration and FAQ & troubleshooting, two H3s under Installation, and a # line inside a code block:
- Installation
- [Installation](#installation)
- On macOS (H3)
- indented under Installation, #on-macos
- FAQ & troubleshooting
- #faq--troubleshooting
- # inside the code block
- ignored
Five entries in two levels, with the ampersand dropped from the anchor just as GitHub does.
Anchors that match GitHub
Each link points to the anchor GitHub, GitLab and most documentation sites generate: the heading in lowercase, punctuation removed and spaces turned into hyphens. Repeated headings get -1, -2 suffixes, just as GitHub numbers them.
Headings inside fenced code blocks are ignored, so a # comment in a shell snippet doesn't end up in the contents. Underlined headings (=== and ---) are recognised as well as # ones.
Frequently asked questions
Why doesn't a TOC link work on my site?
Some sites create anchors differently. GitHub's style is used here; check one heading's anchor on your site and compare.
Should the H1 be in the table of contents?
Usually not, since it's the document title. Leave Leave out the H1 title ticked.
Can I make a numbered TOC?
Yes. Tick Numbered list for 1., 2., 3. at each level.
Does it update automatically?
No. Paste the document again after changing headings to regenerate it.
Related tools
Markdown Previewer
Live Markdown preview with GitHub tables and code blocks, and HTML output.
Markdown to HTML Converter
Convert Markdown to clean HTML, with GitHub tables and sanitising.
URL Slug Generator
Turn titles into clean, lowercase URL slugs.
Regex Tester
Test JavaScript regular expressions with live highlighting, groups and replace.
Text Diff Checker
Compare two texts by line, word or character and see what changed.
Cron Expression Explainer
Translate a cron schedule into plain English and see its next run times.
More Developer tools
JSON & data
CSV tools
Network & system
Web & API
Git & releases
Encoding & security
- Base64 encode & decode
- URL encode & decode
- JWT decoder
- Hash generator
- HTML entity encoder
- Text to binary
- Morse code translator
- Caesar cipher & ROT13
- Random string generator
- Secret key generator
- 2FA code generator (TOTP)
- Encrypt & decrypt text
- Encrypt & decrypt files
- SSH key generator
- Base32 encoder and decoder
- Unicode escape converter
- Nano ID generator
- JWT generator