How to Generate a Table of Contents from Markdown
Build a Markdown contents list with valid anchors, create a native Word TOC after export, and understand this converter’s HTML and PDF navigation limits.
A table of contents is useful only when its destinations exist in the final format. Markdown can express a list of links, but it has no standard command that creates heading anchors, Word TOC fields, or PDF bookmarks. Those features belong to the renderer or document editor.
Start with a clear heading hierarchy
# Project handbook
## Installation
Installation instructions.
## Usage
### Configuration
Configuration instructions.
Use headings for structure rather than bold paragraphs. This site's DOCX exporter maps heading levels to native Word heading styles, which Word can use to generate a table of contents after export.
A manual TOC for a renderer with heading anchors
On a platform that generates heading IDs, a TOC can be an ordinary list:
## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
The list itself renders in Markdown, but the links work only if the destination headings have matching IDs. GitHub generates section links; other renderers may use different IDs or generate none. Copy a section's actual link from the destination platform instead of assuming that lowercasing its heading is sufficient.
GitHub documents section links and custom anchors. Repeated headings and punctuation can affect the resulting fragment, so recheck links after changing titles.
What this site's preview and HTML support
This converter does not automatically add IDs to plain Markdown headings. Pasting [Installation](#installation) above ## Installation therefore does not, by itself, create a working navigation target here.
For an HTML-specific document, provide an explicit target:
- [Installation](#installation)
<h2 id="installation">Installation</h2>
Installation instructions.
The renderer sanitizes IDs and adjusts matching internal fragment links. Use the Markdown to HTML tool to inspect the resulting ID and link together, then test them in the exported HTML. This sanitizer behavior prevents a source ID from being assumed to be unchanged in the output.
An explicit HTML anchor still does not become a Word bookmark in the current DOCX exporter. Treat HTML navigation and Word navigation as separate output checks.
Create a native table of contents in Word
- Write the document with real
#,##, and###headings. - Export with the Markdown to Word converter.
- Open the DOCX and inspect the heading styles or Navigation Pane.
- Place the cursor where the table of contents belongs.
- Use Word's References → Table of Contents controls to insert a native TOC.
- Update the TOC after final edits or pagination changes.
The export does not insert that field automatically. A manual list copied from Markdown remains ordinary content; it does not acquire page numbers or update itself when headings change. Remove a redundant manual list if you replace it with Word's generated TOC.
PDF navigation needs a suitable export workflow
This site's direct PDF export captures page images. It does not generate active links, heading bookmarks, or a selectable text layer. A visible contents list in that PDF is a visual outline, not interactive navigation.
If navigation and search are requirements, create the DOCX, add its TOC in a document editor, and export using settings that preserve the required links, text, and bookmarks. Open the resulting PDF and try both a TOC entry and a text search before sharing it.
Troubleshoot a broken contents entry
| Symptom | Check | Action |
|---|---|---|
| Clicking does nothing in preview | Target heading has no ID | Add an explicit HTML target or use a renderer with heading IDs |
| One of several identical headings opens the wrong section | Duplicate or platform-specific IDs | Copy the actual destination fragment |
| Word has a list but no page numbers | The list is ordinary Markdown content | Generate a native TOC from Word heading styles |
| Page numbers are stale in Word | TOC was generated before layout edits | Update the field after editing |
| PDF contents are not clickable | Image-based export or link loss | Use a workflow that preserves navigation and verify the final PDF |
Maintain the heading hierarchy in your Markdown source, then build navigation appropriate to each destination. That avoids mistaking a visually correct outline for a functional table of contents.