How to Add a Table of Contents to a Markdown PDF

Generate a TOC from headings

A Markdown converter with TOC support can build a contents page from H2 and H3 headings. This works well for manuals, specifications, proposals, and reports.

Steps

1. Use ## for main TOC sections and ### for subsections.
2. Turn on Cover in the toolbar.
3. Open the cover settings.
4. Enable “Add a table of contents page.”
5. Save the PDF and verify that the TOC appears between the cover and body.

The TOC is assembled during export. If you only inspect the normal body preview, it may not appear there, so review the exported PDF as well.

Use a logical heading hierarchy

Use one # as the document title, ## for primary TOC sections, and ### for supporting subsections. Do not choose a heading level merely for its visual size, and avoid skipping levels.

# Operations Manual
## Introduction
### Purpose
### Audience
## Instructions
### Open a file
### Configure the layout
## FAQ

Prefer descriptive labels such as “Configure PDF margins” over generic labels such as “Settings.” Keep headings concise, use consistent scope at each level, and avoid empty or punctuation-only headings.

If the TOC option is disabled

Check that a heading uses an ASCII # followed by a space, is outside a fenced code block, and that the cover option is on. The editor must recognize at least one heading before the TOC control becomes available.

For formal documents, the sequence “cover → contents → body” is usually clear. A page break before each h1 can also align chapter openings, although it may add excess whitespace in short documents. Always inspect the final exported PDF for missing entries and correct section order.

Understand page references

Primary H2 entries show the page where that section begins. H3 entries provide structure without adding a page number to every detail line, keeping the contents page easier to scan. Page references depend on final pagination and are calculated from the rendered document rather than typed manually.

Any change to margins, font size, cover, background, images, tables, or page breaks can move an H2 to another page. Regenerate the PDF after layout edits and compare every displayed reference with the actual heading page.

Keep the TOC concise

A TOC should help a reader choose a destination quickly. Merge tiny sections, replace generic headings such as “Details” with meaningful labels, and avoid repeating the full document title as a section. H3 is useful when it distinguishes a few major subtopics; dozens of minor H3 entries create noise.

For a short document, a cover without a TOC may be more efficient. For a long specification, group sections by reader task and keep the same grammatical style across headings.

Troubleshoot missing entries

Confirm that the heading starts with ASCII ## or ###, followed by a space, and is outside a code fence. Bold text is not a heading. Raw HTML headings may not participate in the same extraction path. If the TOC control is unavailable, choose a cover template and confirm that at least one eligible heading exists.

Duplicate headings are understandable in prose but ambiguous in navigation. Rename them with context, for example “Installation prerequisites” and “Export prerequisites.” This also improves page anchors and search clarity.

TOC preflight checklist

• One H1 identifies the document title.
• H2 entries represent main reader destinations.
• H3 entries are limited to useful subdivisions.
• No heading level is skipped for visual styling.
• Cover and TOC controls are enabled.
• Entry order matches the body.
• Every H2 page reference is correct.
• The contents page itself fits cleanly.
• The PDF was regenerated after the final layout change.

Frequently asked questions

Why do H3 entries have no page number?

Page references are intentionally reserved for H2 sections so the right edge remains clean and useful. H3 entries still communicate hierarchy beneath their parent section.

Can I type page numbers manually?

You can write text, but it becomes stale whenever pagination changes. Generated references are safer. Verify them only after the final page-break and margin adjustments.

See how to control Markdown PDF page breaks when correct headings appear on unexpected pages.