Guide
Page breaks in Markdown — usually you don't have to think about them
The PDF renderer handles 95% of page-break decisions for you. The remaining 5% is worth knowing about: when a heading orphans, when a table is too tall, when you really do want a forced break.
By Elia Kuratli
·3 min read
Open the converterWhat the converter does for you
- Orphan guard for headings. A heading near the bottom of a page gets pushed to the next page if there is not at least four body lines of room below it. So you never see a heading sitting alone at the end of a page.
- Section clustering. A heading plus its first body block are kept together, so you never get a heading on one page and its first paragraph on the next.
- Table splitting. Short tables stay on one page. Long tables (over ~30 rows) split, with the header repeated on the next page.
- Code-block splitting. Code blocks of 14 lines or fewer stay on one page. Longer ones split.
Forcing a page break
The converter does not respond to <div style="page-break-before"> or similar HTML hacks. Instead, structure the Markdown so the breaks land where you want:
- For a true new page before a section, lead it with an H1. H1s do not auto-break in this tool (they cluster with their first paragraph instead) — but the section-keeping logic will push short preceding content together so the H1 ends up at the top of its own page in practice.
- If a paragraph is sitting awkwardly, break it into shorter paragraphs. A paragraph that fits in ten lines on a page is much easier for the renderer to lay out than one that fits in twenty.
What about \\pagebreak and other LaTeX-isms?
We do not parse LaTeX. If you need fine-grained page-break control, Pandoc + LaTeX is still the right tool — see the Pandoc-alternative comparison.