Long Markdown, Real Page Numbers
A 300-page manual is where a converter either earns trust or falls apart. The first thing readers check is the table of contents.
On this page
The TOC problem is a timing problem
A converter that renders once has to answer an impossible question: what page will section 4 be on, before the pages exist?
Most tools guess. They count headings, assume each chapter starts a new page, and write the numbers into the table of contents. Then a long table pushes everything two pages later, and every number after it is wrong.
The document still opens. The TOC is just quietly lying.
What two passes buy you
The fix is not smarter estimating. It is measuring:
- Render the whole document once, without trusting the TOC.
- Read the final page number of every heading out of the rendered PDF.
- Write those numbers back into the TOC and re-render the affected pages.
That is slower than a single pass, and it is the only way the numbers can be right after a 40-page table.
Bookmarks are the real navigation
Print readers use the TOC. Screen readers and most PDF viewers use the bookmark tree, which comes from heading levels.
If a PDF has a TOC but no bookmarks, it looks finished and behaves like a stack of images. Checking the bookmark panel is the fastest way to tell whether an export is actually navigable.
A checklist for long exports
- Export something longer than you would publish. A 20-page sample will not show the drift.
- Put a long table before a TOC entry. That is the case that breaks single-pass numbering.
- Open the bookmark panel. Every heading level you care about should be there.
- Change one margin and export again. If the TOC numbers do not move, they were never measured.
Try it with a manual
The field manual sample below covers chapter breaks and navigation settings. If you want a document that already has a table of contents, numbered sections and a table, open the field manual sample and export it before building your own.
For shorter documents, start from the Markdown studio.
What we do not claim
Very large documents still take longer to render, and the TOC is only as accurate as the final layout: if you change margins, page size or chapter break rules, the numbers must be measured again. Documents with hundreds of pages are part of the regression suite; they are not an infinite guarantee.
The same renderer is one click away. Open a working sample and export it before pasting your own Markdown.