Markdown page break: rules, divs and raw blocks in pandoc

You put three dashes between two parts of a file and hoped the second part would start on a fresh page. Pandoc handed back a horizontal line instead.

One test pass under macOS, running pandoc 3.8.3, produced the output quoted here. It covers markdown page break input of five kinds: three dashes, a hand-typed div carrying a break style, a \newpage line, and raw blocks tagged for HTML and for LaTeX. Each output quoted below comes from those runs, read as HTML or as -t latex output.

Page breaks in plain CommonMark

Nowhere does the spec file for CommonMark 0.31.2 use the word page. Run with grep -ci 'page', a search that ignores case, it matched 0 lines. The control, grep -ci 'thematic break' on that same file, found 20.

The dashes test, pb-hr.md, held two short paragraphs with a dashed line between them. Pandoc's commonmark reader and its markdown reader both returned <p>Page one.</p>, then <hr />, then <p>Page two.</p>. That is a horizontal rule, and nothing in the output asks for a new page. The guide to horizontal rules covers the syntax behind it.

Pandoc's extension listing showed +raw_html and -raw_attribute under commonmark, and +raw_html with +raw_attribute under markdown. Both extensions come up again in the sections that follow.

A break style on a typed div

The next test file, pb-div.md, put an empty div with a style between the two paragraphs:

Page one.

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

Page two.

The two readers kept the style. They laid out the tags in different ways.

The commonmark reader (pandoc -f commonmark -t html pb-div.md) kept the div on one line and added a blank line after it:

<p>Page one.</p>
<div style="page-break-after: always"></div>

<p>Page two.</p>

The markdown reader (pandoc -f markdown -t html pb-div.md) split the opening and closing tags onto separate lines, and a blank line sat between the two:

<p>Page one.</p>
<div style="page-break-after: always">

</div>
<p>Page two.</p>

In both runs, the page-break-after: always style reached the output exactly as typed. Pandoc's part ends at that attribute. What any program does with that HTML after pandoc writes it was outside this test.

Blank-line rules around hand-typed tags are covered in the explainer on HTML you type by hand. A div that centers text gets its own runs in the post on centering text.

The newpage command

A \newpage line sat by itself in pb-newpage.md. Pandoc's extension listing for the markdown reader includes +raw_tex; the listing for commonmark has no raw_tex entry. The file:

Page one.

\newpage

Page two.

Three runs gave three results:

• pandoc -f commonmark -t html pb-newpage.md kept the line as text: <p>\newpage</p>.
• pandoc -f markdown -t html pb-newpage.md dropped it. Only <p>Page one.</p> and <p>Page two.</p> came back.
• pandoc -f markdown -t latex pb-newpage.md kept \newpage between Page one. and Page two., with empty lines around it.

So the same line went three ways. The HTML from the commonmark reader shows the backslash and the word. The HTML from the markdown reader loses the line. The LaTeX from the markdown reader keeps it as typed.

A raw block for HTML output

The file pb-rawattr.md tagged a fenced block {=html}. Pandoc's extension listing had raw_attribute on for markdown and off for commonmark:

Page one.

```{=html}
<div style="break-after: page"></div>
```

Page two.

Four runs, one per reader and format:

• pandoc -f markdown -t html pb-rawattr.md gave <div style="break-after: page"></div> on its own line between the two paragraphs.
• pandoc -f commonmark+raw_attribute -t html pb-rawattr.md gave that same div line, then a blank line, then <p>Page two.</p>.
• Without raw_attribute, pandoc -f commonmark -t html pb-rawattr.md turned the block into code: <pre class="{=html}"><code>&lt;div style=&quot;break-after: page&quot;&gt;&lt;/div&gt;</code></pre>.
• pandoc -f markdown -t latex pb-rawattr.md dropped the block. Only Page one. and Page two. came back.

With raw_attribute off, {=html} landed in the class attribute of a <pre> element, and the div showed up as escaped text. With it on, the div passed through. The LaTeX run left out the HTML block.

A raw block for LaTeX output

A follow-up test, pb-x-rawlatex.md, swapped the tag to {=latex} and put \newpage inside:

Page one.

```{=latex}
\newpage
```

Page two.

Here's what came back:

• pandoc -f markdown -t latex pb-x-rawlatex.md gave \newpage on its own line between the paragraphs.
• pandoc -f commonmark+raw_attribute -t latex pb-x-rawlatex.md matched that output line for line.
• pandoc -f markdown -t html pb-x-rawlatex.md dropped the block, leaving <p>Page one.</p> and <p>Page two.</p>.
• Without raw_attribute, pandoc -f commonmark -t latex pb-x-rawlatex.md wrapped the line in Shaded and Highlighting blocks, with the line itself written as \NormalTok{\textbackslash{}newpage}.

Put next to the previous section, the pattern holds in both directions. With raw_attribute on, in these runs, a block tagged for one format reached that format's output and went missing from the other.

Test a break on its own

When a break you typed doesn't show up in pandoc's output, test the lines around it by themselves.

1. Copy the break line and the paragraphs on each side into a new, empty file.
2. First, try the commonmark reader with no extensions added. pandoc -f commonmark -t html pb-hr.md | grep -c '<hr />' gave 1 for the dashed file.
3. For a typed div, count the style: pandoc -f commonmark -t html pb-div.md | grep -c 'page-break-after' gave 1.
4. For a tagged block, compare reader settings. pandoc -f commonmark -t html pb-rawattr.md | grep -c '<div' gave 0, and pandoc -f commonmark+raw_attribute -t html pb-rawattr.md | grep -c '<div' gave 1.
5. For a \newpage line, match the output format. pandoc -f markdown -t latex pb-newpage.md | grep -c 'newpage' gave 1, and pandoc -f markdown -t html pb-newpage.md | grep -c 'newpage' gave 0.
6. A 0 from one of these counts sends you back to the section on that kind of input.

Where Sashmark fits

Planned for v1: in-place editing, so you could change text directly on the planned rendered page. The plan calls for a clean Round-Trip as well, so untouched lines would be written back unchanged, byte for byte. Sashmark also plans a Changes View. It would flag the parts of the file that differ from your previous reading, and it would require no git. It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

Updates on the project: sashmark.com.