Markdown Page Break: Force a New Page in PDF Exports

There is no native markdown page break syntax, because Markdown targets HTML and web pages don't have pages. The fix depends on what turns your file into a PDF. Browser-based exporters take an HTML <div> with a CSS break, Pandoc and R Markdown take \newpage, and Quarto takes a shortcode. This post gives you the one line that works for each tool.

Why Markdown Has No Page-Break Syntax

CommonMark defines how Markdown becomes HTML, and HTML is one continuous scroll. Pages only appear when something prints that HTML to paper or PDF, and at that moment the print engine decides where to cut. So a Markdown page break is always an instruction to the exporter, never to Markdown itself.

That also explains two common mix-ups. Three hyphens (---) make a horizontal rule, a visible line, not a new page; see the Markdown horizontal line guide if that's what you wanted. And two trailing spaces make a line break inside a paragraph, covered in the Markdown line break post. Neither moves content to a new page. If you searched for "markdown break page" or "markdown new page", the answer is below.

How Do You Insert a Markdown Page-Break for PDF?

Most Markdown-to-PDF tools render your file to HTML and print it with a browser engine. For those, drop this line on its own, with a blank line above and below, wherever you want the next page to start:

Text on the first page.

<div style="page-break-after: always;"></div>

Text on the second page.

The page-break-after: always declaration is the legacy CSS property. MDN's break-after reference documents the modern equivalent, break-after: page, and notes that browsers treat page-break-after as an alias of break-after for backward compatibility. Both work in current Chromium-based exporters. We use the legacy form because older tools that predate the alias still honour it, and nothing modern has dropped it.

You can also break before an element instead of after an empty one. Adding style="break-before: page" to a heading's wrapper does the same job, but Markdown headings can't take attributes without HTML, so the empty div stays the most portable form.

Test the Markdown Page-Break in a Real PDF

We checked the snippet against our own Markdown to PDF converter. A document with two page-break divs came back as a three-page PDF, and both the page-break-after: always form and the break-after: page form produced a break. Try it below. Click Export PDF and count the pages.

The preview pane shows nothing at the break, because a div with no content has no height on screen. That's expected. The break exists only in the paged output.

Markdown Page Break by Tool

The snippet above covers browser-based exporters. Other toolchains need their own line. This table is the whole post in one place.

Tool	What to write	Notes
Our md-to-pdf converter and other browser-print exporters (VS Code's Markdown PDF extension, for example)	<div style="page-break-after: always;"></div>	Tested in our converter; the div must be outside code blocks
Obsidian (Export to PDF)	<div style="page-break-after: always;"></div>	The fix most often shared on the Obsidian forum; add it before the heading you want on the new page
Pandoc to PDF via LaTeX	\newpage	Raw TeX passes through when the output is LaTeX-based
Pandoc to DOCX	\newpage plus the pagebreak Lua filter	The filter turns \newpage or \pagebreak into a Word page break
R Markdown	\newpage	Works for PDF, Word, HTML, and ODT output; rmarkdown ships the Lua filter
Quarto	{{< pagebreak >}} shortcode	Native breaks for HTML, LaTeX, ConTeXt, Word, ODT, ePub, and Typst
GitHub, GitLab, most wikis	Nothing works	Rendering is on-screen only, and GitHub's sanitizer removes style attributes

Two rows deserve detail. The R Markdown Cookbook explains that \newpage is a LaTeX command, but rmarkdown recognises it for HTML, Word, and ODT output too, using Pandoc Lua filters under the hood. For HTML the break only shows when you print the page.

Quarto's Markdown basics page states that its shortcode gives native page breaks in HTML, LaTeX, ConTeXt, MS Word, Open Document, ePub, and Typst. Elsewhere it falls back to a form-feed character. If you're writing a report that has to export to both PDF and Word, Quarto's shortcode is the one syntax that needs no per-format workaround. The R Markdown cheat sheet covers the wider Rmd syntax if you're on that side.

Pandoc Page Breaks for PDF and DOCX

Pandoc behaves differently depending on the output format, which trips people up. When the target is PDF through a LaTeX engine (the default), a bare \newpage line is passed through as raw TeX. It produces a page break:

Section one ends here.

\newpage

Section two starts on a new page.

For Word output, LaTeX commands mean nothing, so the same \newpage disappears. The fix is the pagebreak filter maintained by the Pandoc team. Its README says the filter converts paragraphs containing \newpage or \pagebreak into the right page-break markup for DOCX, EPUB, HTML, LaTeX, ConTeXt, and groff. The README also notes that the code now lives in the pandoc-ext/pagebreak repository. Run it with pandoc report.md --lua-filter pagebreak.lua -o report.docx.

One limitation: Pandoc ignores the HTML div when producing DOCX or LaTeX, because raw HTML is only passed through to HTML-based outputs. Pick the syntax that matches your target, or use the filter so a single \newpage works everywhere.

Common Markdown Page-Break Mistakes

Putting the div inside a code block or list. Fenced code shows the tag as text, and a div indented inside a list item becomes part of the item. Keep it at column 0 with blank lines around it.

Expecting it to work on GitHub. GitHub strips style attributes during sanitisation, so the div renders as nothing. Page breaks belong in the PDF step, not the README.

Using --- and wondering why the PDF has a line instead of a new page. Three hyphens are a thematic break. Replace them with the div, or keep both if you want a rule at the bottom of the page as well.

Markdown Page-Break FAQ

The right markdown page break is the one your exporter understands: the empty div with page-break-after: always for browser-based tools such as Obsidian, VS Code, and our converter; \newpage for Pandoc and R Markdown; and the pagebreak shortcode for Quarto. Paste your document into the editor, add the break, export a PDF, and check that the page count matches.