Page Breaks in Markdown

Page breaks in MDTool’s PDF converter

MDTool’s Markdown to PDF converter recognizes four markers. Put any one of them on its own line, with a blank line above and below, and the content after it starts on a new page. The first two are HTML, the third is an HTML comment, and the last two are LaTeX-style commands, so you can keep whichever convention your files already use.

End of chapter one.

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

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

<!-- pagebreak -->

\pagebreak

\newpage

# Chapter two

Pandoc: \newpage and \pagebreak

When Pandoc produces a PDF through LaTeX, raw TeX commands in the Markdown pass straight through to the LaTeX engine, so \newpage or \pagebreak on its own line starts a new page. Other output formats ignore raw LaTeX: HTML drops it, and Word (.docx) output has traditionally needed a page-break filter to turn it into a real Word page break.

Introduction ends here.

\newpage

# Methods

$ pandoc report.md -o report.pdf

VS Code Markdown PDF, Typora and Obsidian

Desktop tools each have their own convention. The popular Markdown PDF extension for VS Code (yzane) uses a div with the class "page". Typora documents a div with both the old and the new CSS page-break properties, and can also start every H1 on a new page with a CSS rule. Obsidian has no built-in marker; users add a CSS snippet for print (for example turning --- into a page break) or install a page-break plugin.

<!-- VS Code: Markdown PDF extension -->
<div class="page"/>

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

Page break syntax by tool

Use this table to pick the marker for the tool that produces your PDF.

Which marker should you use?

If the same file is also read on GitHub, prefer <!-- pagebreak --> or the page-break div: both are invisible on the web, while \newpage and \pagebreak appear as literal text there. If you convert only with Pandoc to LaTeX, \newpage is the natural choice. The style="page-break-after: always;" div is the most portable, since any HTML-based PDF engine understands the CSS.

Common pitfalls

A marker inside a code block or an indented line is treated as code and does nothing. A marker that shares a line with other text is usually ignored. A horizontal rule (---) only draws a line and never breaks the page. And a marker at the very end of the document, or two markers in a row, can leave an empty page behind.