How to Generate a Table of Contents from Markdown
Auto-generate a table of contents from Markdown headings. Learn manual TOC syntax, auto-TOC tools, anchor links, and exporting a TOC to Word.
A long Markdown document without navigation is a wall of text. When you generate a table of contents from Markdown headings, readers can jump to the section they care about, and you get a clean outline you can reuse in Word, PDF, or HTML output. This guide walks through manual TOC syntax, automatic generation from headings, anchor link rules, and exporting the result so you can build a Markdown table of contents fast.
Why Generate a Table of Contents from Markdown
A table of contents (TOC) solves three real problems in long-form Markdown:
- Navigation — readers skip to the section they need instead of scrolling.
- Structure — you spot missing, duplicated, or unbalanced headings before publishing.
- Reuse — the same TOC outline can be carried into a Word
.docx, a PDF, or an HTML page.
Markdown itself has no single built-in TOC command. Instead, a TOC is just a list of links pointing to heading anchors (the id attribute each renderer assigns to your headings). That means you have two strategies: write the list by hand, or generate it from your headings with a tool. Most writers start manual and then switch to auto-generation once a document grows past a few screens.
Build a Manual Table of Contents in Markdown
For short documents, a hand-written TOC is fast, transparent, and portable. You use a standard unordered list where each item is a link to an anchor:
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [CLI Options](#cli-options)
- [Configuration](#configuration)
- [FAQ](#faq)
A few rules keep manual TOCs consistent across renderers:
- Every link target must match a real heading in the document.
- Nested list indentation (two spaces per level) reflects your heading hierarchy.
- Anchor text should match the heading, minus punctuation.
A manual TOC is the most portable form — it renders everywhere Markdown does, including static-site generators, GitHub, and plain preview windows.
The downside is maintenance. If you rename or reorder a heading, you must update the TOC by hand. Automate it and you stop fighting that drift.
Auto-Generate a Table of Contents from Markdown Headings
When a document grows, generating the TOC from your #, ##, and ### headings is safer than typing it. Common approaches:
| Method | Tool / Flavor | How it works |
|---|---|---|
| TOC marker | markdown-toc, doctoc | Insert a marker comment, regenerate on save |
| Renderer TOC | Jekyll, Docusaurus, Hugo | {% toc %} / built-in from headings |
| VS Code extension | Markdown All in One | Command creates/updates TOC from headings |
| CLI script | markdown-toc (npm) | markdown-toc -i README.md updates in place |
Example using the npm markdown-toc package with the in-place flag:
npx markdown-toc -i README.md
The tool reads every heading, builds the anchors, and writes the list back between marker comments that look like <!-- toc --> and <!-- tocstop -->. Re-run it whenever headings change.
For static-site generators, prefer the built-in TOC directive over a manual list so the outline is always in sync with the headings, even after big edits.
Add Anchor Links to a Markdown Table of Contents
Anchor links are what make a Markdown TOC clickable. Each renderer derives the anchor from the heading text with slightly different rules, which is why a TOC that works on GitHub may break elsewhere. GitHub Flavored Markdown (GFM) follows these conventions:
- Lowercase the heading text.
- Strip punctuation other than hyphens and underscores.
- Replace spaces with hyphens.
- Deduplicate repeats by appending
-1,-2, and so on.
So ## API Reference becomes #api-reference, and ## What's New? becomes #whats-new.
- [API Reference](#api-reference)
- [What's New?](#whats-new)
If two headings produce the same slug, the second one gets
-1. Always verify anchors after renaming headings.
A quick cross-check is to hover an existing heading in the rendered view and copy its link — that is the exact anchor your TOC must reference.
Export a Markdown Table of Contents to Word
A TOC in your Markdown is useful, but most reviewers still expect a Word document with a real, clickable table of contents field. The path is: write Markdown with heading levels, convert it, and let Word rebuild the TOC field.
When you paste or import a converted .docx into Word, the headings become Word Heading 1 / Heading 2 styles. Word's References > Table of Contents then generates a native TOC from those styles, complete with page numbers and clickable links. You can try this export directly in the Markdown to Word converter.
For a one-page outline instead of a page-numbered TOC, the Markdown to HTML route also gives you a single self-contained file whose heading links still work. If your goal is print, the Markdown to PDF export preserves those heading styles so the PDF keeps a navigable outline pane.
Conclusion: Build a Markdown Table of Contents Fast
A Markdown table of contents is just a list of anchor links, but generating it from your headings — by hand for short docs, automatically for long ones — keeps navigation accurate as the document evolves. Start with a manual list, switch to a generator once headings churn, and lean on consistent anchor rules so links survive across renderers. When it's time to share, export to a Word document where the TOC becomes a native, clickable field, or use Markdown to PDF and Markdown to HTML for archive and web outputs. Browse more Markdown tutorials to keep your writing workflow fast.