How to Control Page Breaks, Tables, and Code Blocks When Converting Markdown to PDF

Control Markdown-to-PDF pagination with print CSS: request breaks before or after sections, avoid splitting rows, figures, and short code blocks, and reserve enough page margin. These rules are requests to the print engine, not guarantees. Test the actual PDF, especially when a single table row, image, or code block exceeds one printable page.

Broken pagination is usually a layout constraint, not malformed Markdown. This guide is for developers and technical writers exporting through an HTML-and-browser print path. It explains portable CSS guidance based on CSS and MDN documentation; it does not claim how any particular converter, including SolConverter, implements print options.

For the broader pipeline choices, read the Markdown-to-PDF guide. If the document is large or fails intermittently, the large-document reliability guide covers fixture design and renderer isolation.

Why browser PDFs do not behave like typeset documents

A browser normally lays out a continuous web page, then fragments that layout into printable pages. CSS fragmentation rules let authors express preferred break points and avoidance rules, but the engine must still fit content into finite page boxes. A dedicated paginated-layout system can make different choices because pagination is its primary layout model.

That distinction matters when a document contains a wide table, a 90-line code sample, or an image taller than the available page area. break-inside: avoid can keep a block together only while it fits. If it does not, the engine must split it, overflow it, scale it, or leave an undesirable gap. The CSS Fragmentation specification defines this class of break controls and their trade-offs.

Use print rules as progressive improvement. Keep the HTML structure semantic first, then test in the exact browser and PDF path that will produce the deliverable.

Start with a print stylesheet

Keep screen styles and print styles separate where practical. This baseline gives the PDF a predictable page area and avoids screen-only decoration.

@media print {
  nav,
  .app-toolbar,
  .no-print {
    display: none;
  }

  .document {
    max-width: none;
  }
}

@page {
  size: A4;
  margin: 18mm 16mm 20mm;
}

The @page rule on MDN documents page size and margins. Treat size as a request that must agree with the PDF job or browser print settings; a user-selected paper size can override your expectation.

Put deliberate breaks at document boundaries

Use the modern break-* properties. The older page-break-* properties remain useful as fallbacks for older engines, but break-before, break-after, and break-inside describe fragmentation more clearly.

@media print {
  .chapter {
    break-before: page;
    page-break-before: always; /* legacy fallback */
  }

  .appendix-end {
    break-after: page;
    page-break-after: always; /* legacy fallback */
  }

  .keep-together {
    break-inside: avoid;
    page-break-inside: avoid; /* legacy fallback */
  }
}

Apply break-before: page to meaningful boundaries such as a chapter, appendix, or major report section—not every H2. Too many forced breaks create blank space and can make later pagination worse. See MDN for break-before, break-after, and break-inside.

Keep headings with their content and reduce text orphans

An orphaned heading is usually more distracting than an extra line of whitespace. Ask the engine not to break immediately after a heading, and make the first following block eligible to stay with it.

@media print {
  h2,
  h3,
  h4 {
    break-after: avoid;
    page-break-after: avoid;
  }

  h2 + p,
  h2 + ul,
  h2 + ol,
  h2 + pre,
  h3 + p {
    break-before: avoid;
  }

  p,
  li {
    orphans: 3;
    widows: 3;
  }
}

orphans and widows control the minimum lines left at the bottom and top of pages for a block of text; they do not make a heading and its paragraph inseparable by themselves. Their support and effect can vary by print engine, so confirm the generated PDF. MDN describes orphans and widows.

Make long tables readable across pages

Use real table elements in the generated HTML: table, thead, tbody, tr, th, and td. For a table that may run across pages, allow the table itself to fragment, repeat its header where supported, and avoid splitting an individual row when it fits.

@media print {
  table {
    width: 100%;
    border-collapse: collapse;
  }

  thead {
    display: table-header-group;
  }

  tfoot {
    display: table-footer-group;
  }

  tr,
  th,
  td {
    break-inside: avoid;
    page-break-inside: avoid;
  }

  th,
  td {
    overflow-wrap: anywhere;
    vertical-align: top;
  }
}

Do not put break-inside: avoid on the entire long table: it can cause a huge blank area or force an impractical layout. A header group may repeat in browser print output, but test it in the target path; the CSS Tables specification leaves some fragmentation details to user-agent behavior.

A realistic pagination failure checklist

Make long tables readable across pages

Symptom	Probable cause	Safe mitigation	Limitation
Heading sits alone at the page bottom	No break avoidance between the heading and following content	Add break-after: avoid to headings and test with representative text	A heading plus its following block may still be too tall for the remaining space
Table header appears only on page one	Header cells are not in thead, or the print engine does not repeat the group	Use semantic thead and display: table-header-group	Repeated headers are engine-dependent and do not fix an over-wide table
A row is cut in half	The row can fragment or its content is taller than the page	Apply break-inside: avoid to rows; shorten or split oversized cell content	A row taller than one printable page cannot remain whole
Code is clipped at the right edge	Long unbroken tokens or screen-only horizontal scrolling	Use overflow-wrap: anywhere for prose and choose a code wrapping policy	Wrapping code changes its visual line structure; horizontal overflow can still be preferable
Figure separates from its caption	Figure and caption are independently fragmentable	Wrap both in figure and use break-inside: avoid	A figure plus caption taller than a page must be scaled, split, or moved

Handle code blocks longer than a page deliberately

First decide whether code must preserve its original horizontal lines. For reading-oriented PDFs, wrapping long lines prevents clipping. For review or copy-and-paste workflows, a landscape appendix, smaller type, or a separately attached source file may be more honest than aggressive wrapping.

@media print {
  pre {
    break-inside: avoid;
    page-break-inside: avoid;
    max-width: 100%;
    white-space: pre-wrap;
    overflow-wrap: anywhere;
    tab-size: 2;
  }

  code {
    overflow-wrap: anywhere;
  }
}

For code exceeding one page in height, break-inside: avoid is impossible to honor completely. The safe choice is to let it break, split the source into logical excerpts, move the full listing to an appendix, or link to the canonical source. Avoid hiding overflow: it can silently remove lines from the PDF.

If code needs a different page shape, give only that content a deliberate structural boundary, such as an appendix rendered in landscape by a PDF workflow that actually supports per-section page settings. Plain browser print CSS cannot be assumed to switch one arbitrary section between portrait and landscape reliably.

Keep figures, images, and captions in the same conversation

Use a semantic figure and figcaption in the HTML produced from Markdown where your renderer supports it. Then constrain images to the printable width and prevent avoidable separation.

@media print {
  figure {
    break-inside: avoid;
    page-break-inside: avoid;
    margin: 1rem 0;
  }

  figure img,
  figure svg {
    display: block;
    max-width: 100%;
    height: auto;
  }

  figcaption {
    break-before: avoid;
  }
}

An image that is taller than the printable page area needs a content decision: reduce it proportionally, crop it with an explicit source alternative, divide it into labeled panels, or give it its own page. CSS cannot keep an over-page-height figure intact without changing one of those constraints.

Margins, page headers, and footers: know the browser boundary

@page can set page dimensions and margins. CSS Paged Media also specifies margin boxes such as @top-center, which can describe running headers and footers in paged-media implementations. Do not assume those margin boxes work in ordinary browser PDF export: support is not universal, and browser print dialogs may add their own date, title, URL, or page-number header/footer depending on user settings.

@page {
  size: Letter;
  margin: 18mm 15mm 22mm;
}

/* A paged-media feature, not a portable browser-PDF promise. */
@page {
  @bottom-center {
    content: counter(page);
  }
}

Before relying on page numbers or running headers, verify the actual export engine and its configuration. Browser UI header/footer controls are outside ordinary document CSS. A server-side PDF API may offer separate header/footer templates, but that is an implementation capability to verify, not a general CSS guarantee. See the CSS Paged Media Module for the model and MDN’s printing guide for browser-oriented print styling.

A practical testing sequence

Use a small fixture before applying rules to a large handbook:

1. Place an H2 near a page boundary with a paragraph and a list after it.
2. Add a multi-page table with thead, one tall row, and long unbroken text.
3. Add a code block both slightly shorter and slightly taller than one printable page.
4. Add a wide diagram, a tall image, and captions.
5. Export with the same paper size, margins, fonts, browser version, and PDF settings used in production.
6. Review the rendered PDF visually, not only the source HTML.

Record the fixture and rendered PDF with the browser and font versions. That evidence separates a general CSS recommendation from verified behavior in your delivery path. For automation concerns beyond layout, see the Markdown-to-PDF API guide.

Next step

Start with the smallest rule that addresses an observed failure, then re-test the full document. Print CSS can improve pagination substantially, but content that exceeds a page still requires an editorial or layout decision.

Open the Markdown-to-PDF converter

References

• MDN: CSS paged media
• MDN: CSS fragmentation
• CSS Fragmentation Module Level 3
• CSS Paged Media Module Level 3
• CSS Tables Module Level 3