Markdown PDF Page Break CSS: Insert Breaks Anywhere

CSS can control Markdown PDF page breaks

When converting Markdown documents—specs, reports, meeting notes—to PDF, things often go wrong:

• A heading is stranded at the bottom of a page
• A table is split across two pages
• A key section breaks at an awkward line

Pagination is often difficult to reason about because the break is calculated only after Markdown becomes printable HTML. This guide focuses on copy-ready CSS recipes, when to use each rule, and the conditions that commonly make them fail.

The shortest way to force a break at an exact position is this one line. Put it immediately before the next section when your Markdown pipeline permits HTML and inline styles.

<div style="break-before: page"></div>

Choose the page-break rule by symptom

Fix the paper size, margins, and scale before fine-tuning breaks. Changing print geometry later shifts pagination even when the CSS stays the same.

Markdown has no “page” syntax

Markdown is a flowing text format—there is no standard “insert page break here” syntax. Pagination begins after HTML conversion, through print CSS. Embedding <div style="page-break-after: always;"> in .md works in some pipelines, but it hurts source readability and forces edits whenever the layout changes.

Add Markdown PDF page breaks with CSS

If your converter preserves HTML and lets you provide print CSS, put an empty element immediately before the point where the next page should begin.

<div class="page-break"></div>

## Next chapter

@media print {
  .page-break {
    break-before: page;
  }
}

Where inline styles are allowed, this also works:

<div style="break-before: page"></div>

Use modern break-before for new CSS. Some older PDF engines support the legacy page-break-before: always; test before adding it for compatibility.

break-before, break-after, and break-inside

For chapter headings, target h2 in print CSS instead of inserting an element before every chapter. Avoid applying it to the first heading, which can create a blank first page.

@media print {
  h2 {
    break-before: page;
  }
  table, pre {
    break-inside: avoid;
  }
}

break-inside: avoid means “avoid splitting where possible,” not a guarantee. A table or code block taller than a page may still split, or move to the next page and leave whitespace. Always verify in print preview.

Keep a heading off the bottom of a page

A break immediately after a heading leaves an orphan heading on the previous page. Discourage breaks after the heading and before its first paragraph.

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

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

Keep tables, code, and figures together

Short tables, code blocks, and figures are easier to read when they move as a unit. For a table longer than one page, avoid breaking individual rows instead of the entire table to reduce large blank areas.

@media print {
  pre,
  figure,
  blockquote,
  tr {
    break-inside: avoid;
  }

  thead {
    display: table-header-group;
  }
}

Avoid a blank page before the first heading

Applying break-before to every h2 can move the first body heading and leave page one blank. When the headings share one parent, exclude the first h2.

@media print {
  h2:not(:first-of-type) {
    break-before: page;
  }
}

Wrapper markup changes how :first-of-type is evaluated, so inspect the converted HTML and print preview.

Save as PDF also depends on margins, paper size, orientation, and scaling—not CSS alone.

After you change paper, orientation, cover, or TOC

Changing A4/Letter, portrait/landscape, or adding a cover/TOC can shift where breaks fall. Scroll the whole preview to catch unwanted blank pages (e.g. a “break before heading” rule hitting right after a cover). Re-check breaks around landscape pages if you mix orientations.

---

Before adding raw HTML to Markdown

Not every Markdown platform keeps HTML, class, and style attributes. Services may sanitize them for security, and screen-only CSS will not affect a PDF. Confirm that the converted HTML is preserved, put the rule inside @media print, fix paper settings before testing, and do not put break-before and break-after on the same boundary.

If CSS applies on screen but not in the exported PDF, see Why CSS Doesn't Apply to Markdown HTML — 4 Causes and Fixes.

Fix page-break CSS and blank-page problems

For empty-page-only problems, use the focused blank-page troubleshooting guide.

Keep page-break rules out of the Markdown source

Inline HTML is convenient for a one-off break, but it becomes a maintenance problem when the same Markdown is published to GitHub, a CMS, or a wiki. Reusable rules should live in a separate print stylesheet whenever the export pipeline supports one.

@media print {
  h2 {
    break-after: avoid;
  }

  table,
  pre,
  figure {
    break-inside: avoid;
  }
}

Standard Markdown does not carry enough information to identify one arbitrary break position. That requires an HTML marker, an exporter-specific extension, or a post-processing step. Rules such as “every h2” or “every table,” however, can remain entirely outside the source.

FAQ

Can Markdown insert a page break by itself?

Standard Markdown has no page-break syntax. Use HTML plus print CSS where your tool allows it, or use the tool's own page-break feature.

Should I use page-break-before: always or break-before: page?

Start with break-before: page in new stylesheets. Add the legacy declaration only when you have tested an older PDF engine that needs it. Check the final PDF for blank pages.

Why did a blank page appear after I added CSS?

A break-after on the preceding element and a break-before on the following element can duplicate a break. Check cover/TOC rules and heading-wide rules too, then retain one rule for each boundary. See How to Remove Blank Pages from Markdown PDFs for a focused checklist.

Final checks before exporting the PDF

1. Lock the paper size, orientation, margins, and scale first.
2. Use break-before at chapter starts or break-after at chapter ends—not both on the same boundary.
3. Apply break-inside: avoid only when the table or code block can fit on one page.
4. Scan print preview from page one for orphan headings, large gaps, and blank pages.
5. Export, reopen the actual PDF, and verify its page count and section boundaries.

Even correct CSS will paginate differently after a font or margin change alters the number of characters per line. Lock the layout before tuning page breaks to avoid repeating the work.

Try it without writing CSS

Markdown Document Converter can adjust page-break positions in Preview without adding HTML to the Markdown source.

Related articles

• How-to & BlogHow to Remove Blank Pages from a Markdown PDFRemove blank pages from Markdown PDFs by checking page-break rules, margins, oversized content, trailing elements, and print settings.Read article→
• How-to & BlogMarkdown PDF Margins: @page, Print Dialog, and mm SettingsWhy Markdown PDF margins feel wrong—@page vs body padding, browser print dialog presets, asymmetric binding margins, and mm specs. Fix and verify margins step by step.Read article→
• How-to & BlogHow to Fix Broken or Overflowing Markdown TablesDiagnose Markdown tables that are not recognized, have misaligned columns, or overflow HTML and PDF, then fix syntax, long values, width, and pagination.Read article→
• How-to & BlogWhy Markdown PDFs and Print Look Broken — Causes and FixesFix common Markdown-to-PDF and print issues—margins, breaks, missing backgrounds, font substitution, overflowing tables. Includes a triage checklist and browser comparison notes.Read article→