Markdown to PDF with a table of contents
A document over four pages benefits from a ToC. A document over twelve pages requires one. Markdown's heading syntax is enough information to build one - the converter does the work for you.
How the ToC is built
Every H1 becomes a top-level entry. H2s indent under their parent H1. H3s indent further. H4 and deeper are not included - they belong inside a section, not in the high-level navigation.
When 'Numbered headings' is on, the ToC entries get numeric prefixes (1, 1.1, 1.1.2). The same numbers appear on the heading itself in the body, which makes the ToC act as a real cross-reference.
Where the ToC lands in the page sequence
- Cover page (if 'Show cover' is on) - page 1 of the PDF, but excluded from the visible page number sequence.
- Table of contents page - also excluded from the visible numbering, so the body starts at '1'.
- Body - first body page is visible page '1 of N'.
When to turn the ToC off
For a memo, an invoice, a one-page resume, a cover letter, or a quote - the ToC is a tax. The reader should hit the body in two seconds, not navigate to it.
For proposals, reports, white papers and books - the ToC is a navigation aid. Keep it on. Reader trust scales with how easy it is to find a specific section.
FAQ
Are the ToC entries clickable in the PDF?
Page numbers in the rendered ToC are not active links in v1. The PDF outline (visible in any reader's sidebar) does include every heading and is fully clickable.
Can I exclude a heading from the ToC?
Not via a Markdown flag. The ToC is built from every H1 / H2 / H3. If you want to exclude a section, demote its heading to H4 or use a bold mini-label paragraph instead.
Why does my ToC look misaligned?
The ToC indents by heading depth - H1 flush left, H2 indented, H3 indented more. If the indent looks wrong, you probably have an inconsistent heading hierarchy (e.g. an H3 with no parent H2). Fix the structure and the ToC follows.
Related
https://md2document.com/markdown-to-pdf-with-table-of-contents/