Markdown Page Break Tutorial: 4 Methods to Insert Page Breaks

Standard Markdown has no built-in page break syntax. John Gruber designed Markdown for web content, and web pages don't have "pages" — so the feature was never part of the spec. But in practice, we constantly need to export Markdown to PDF, print documents, or generate Word files, all of which require page break control.

This article covers every practical method to insert a markdown page break, from the most universal HTML/CSS approach to tool-specific syntax. Pick the one that matches your workflow.

Method 1: HTML + CSS Page Break (Most Universal)

This is the most widely compatible approach. Nearly all Markdown renderers support inline HTML, and PDF export tools plus browser print functions both recognize CSS page break properties.

Basic Syntax

Insert this HTML where you want the page break:

Content for page one goes here.

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

Content for page two starts here.

page-break-after: always means: force a page break after this element. When exporting to PDF or printing, the renderer will split the content here, and new content begins on the next page.

An alternative with the same effect:

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

This renders both a horizontal rule and a page break. If you don't want the visual line, the <div> version is cleaner.

CSS Page Break Properties Explained

CSS provides three page break related properties, and they often confuse people:

In practice, page-break-after: always covers most needs. break-after is the newer property from CSS Fragmentation Module Level 3, theoretically more powerful (supporting column breaks, region breaks, etc.), but most PDF export tools still recognize page-break-after more reliably.

I ran into this personally when using VS Code's Markdown PDF plugin — page-break-after worked perfectly, but break-after had no effect. Unless you're certain your target tool supports the new standard, stick with page-break-after.

Using page-break-before to Start Sections on New Pages

If you want each major section to always begin on a fresh page (regardless of how much content came before), use page-break-before:

## Chapter 1

Content for chapter one...

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

## Chapter 2

Content for chapter two...

The advantage here is that no matter how long or short chapter one is, chapter two will always start on a new page.

Compatibility

Essentially, this method works for any export or print scenario. The page break won't show up in web previews — which is correct behavior, since web pages are continuous scrolling.

Method 2: Pandoc's \newpage (For Technical Documents)

If you use Pandoc to convert Markdown to PDF or Word (via LaTeX), you can use the LaTeX page break command directly:

Content for chapter one.

\newpage

# Chapter 2

Content for chapter two.

Pandoc passes \newpage straight to the LaTeX engine, which forces a page break at that position.

Supported Output Formats

\newpage in Pandoc isn't limited to PDF — it handles different output formats:

I use this method for most technical reports. One Pandoc command — pandoc report.md -o report.pdf — handles all the page breaks cleanly. Combined with Markdown line breaks and horizontal rules, the layout comes out consistently.

A useful trick: if you need to support both PDF and HTML export from the same document, include both methods:

First page content

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

Second page content

Pandoc picks up \newpage for PDF, and the CSS property handles HTML export. It looks a bit redundant, but it saves headaches in practice.

Method 3: Quarto's pagebreak (For Data Reports)

Quarto is a next-generation publishing tool built on Pandoc, increasingly popular in academic and technical writing. It provides a cleaner page break syntax:

First section content

::: pagebreak
:::

Second section content

::: pagebreak is Quarto's custom div syntax. Quarto automatically selects the right page break method based on your output format — LaTeX for PDF, native breaks for Word, CSS for HTML. You don't need to worry about the underlying details.

Some Quarto templates also support a shortcode syntax:

{{< pagebreak >}}

Same effect as ::: pagebreak. Which one to use depends on your template configuration.

Quarto's approach is the cleanest I've seen — simple syntax, automatic cross-format adaptation, no HTML or LaTeX commands to remember. If you're already using Quarto, this is the way to go.

Method 4: Editor-Specific Syntax

Some Markdown editors define their own page break syntax that only works within their environment.

iA Writer: Three Plus Signs

iA Writer uses three plus signs +++ for page breaks:

First page content

+++

Second page content

When exporting to PDF or printing from iA Writer, +++ is recognized as a page break. Make sure to leave blank lines before and after +++, or it may not be detected.

Typora

Typora doesn't have a proprietary page break syntax, but it fully supports the HTML/CSS method from Method 1. In the editor, the page break tag displays as an HTML block with a dashed border, and it produces clean page breaks when exporting to PDF.

Other Editors

Most Markdown editors (Obsidian, Mark Text, MacDown, etc.) support inline HTML, so the CSS method from Method 1 works across the board. If your editor doesn't support inline HTML, you may need to consider switching tools.

Method Comparison: Which One to Pick?

Recommendations:

• Not sure which to use: Go with Method 1 (HTML + CSS) — nearly all tools recognize it
• Using Pandoc: \newpage is the simplest option
• Using Quarto: ::: pagebreak adapts across formats automatically
• Only using iA Writer: +++ is the most convenient
• Need to support multiple export formats: Combine HTML/CSS and \newpage

FAQ

Does Markdown natively support page breaks?

No. The CommonMark specification defines no page break syntax. Markdown was designed for web content formatting, and web pages are continuous — no pages to break. All page break solutions work through inline HTML, tool extensions, or editor-specific syntax.

Can I use page breaks in a GitHub README?

There's no point. GitHub READMEs display on web pages, which don't have the concept of "pages." CSS page-break properties have no effect in GitHub's rendering environment. Page breaks only matter when exporting to PDF, printing, or generating Word documents.

What's the difference between page-break-after and break-after?

page-break-after is a CSS 2.1 property with broad browser and PDF tool support. break-after is the newer standard from CSS Fragmentation Module Level 3 — more capable (supporting column breaks, region breaks, etc.) but not recognized by some older tools. For Markdown page breaks, page-break-after: always is sufficient.

Why isn't my page break working when exporting to PDF?

Common causes:

1. The renderer doesn't support inline HTML — check if your tool has HTML support enabled
2. Wrong CSS property — confirm it's page-break-after, not page-break or pagebreak
3. No blank lines around the HTML block — leave a blank line before and after the page break tag in your Markdown
4. The PDF engine doesn't process CSS page breaks — try switching to Pandoc

Can I use a horizontal rule (---) as a page break?

No. A Markdown horizontal rule (---, ***, ___) only displays a visual line on the page. Its HTML tag is <hr>, which has no page break functionality — content remains continuous when exporting to PDF. Horizontal rules solve visual separation; page breaks solve physical pagination. Two completely different needs.

References

• CommonMark Spec — Official Markdown specification confirming no native page break syntax
• W3C CSS Fragmentation Module Level 3 — Authoritative definition of CSS page break properties
• Pandoc Manual — Pandoc Markdown extension syntax documentation
• Quarto — Markdown Basics — Official Quarto pagebreak syntax documentation
• R Markdown Cookbook — Page Breaks — Page break solutions in R Markdown