In exporting pages in Confluence to PDF, I wanted to control where page breaks occur. CSS has various properties to control page breaking that I could make use of by manually inserting HTML tags in Confluence pages.
To make tagging easier and consistent, I wrote a user macro that lets me select the type of page break control I want in my terms: “KeepTogether”, “KeepwithPrevious”, “KeepwithNext”, “ForceBreakBefore”, and “ForceBreakAfter”. The macro inserts HTML div tags with the specific class used to reference the CSS property.
pdfcontrolbreak User Macro
## Macro title: pdfcontrolbreak
## Description: Control page breaks in PDF. Typically, before images, tables, and step lists.
## Configuration: pdfcontrolbreak, External Content, Convert wiki markup to HTML, HTML
## Developed by Bruce Michelsen
## Parameters:
## Specify type of control for page break. Typically, before images, tables, and step lists.
## Usage:
## {pdfcontrolbreak:breaktype}
##
## PARAMETER DEFINITIONS
## @param breaktype:title=breaktype|type=enum|enumValues=KeepTogether,KeepwithPrevious,KeepwithNext,ForceBreakBefore,ForceBreakAfter|desc=Specify the PDF page break control type|required=true
##
## DEFAULT VARIABLES AND VALUES
#set ($defvarbreaktype = "Keep Together")
##
## GET AND SET PARAMETERS
## Check for a blank first parameter
#if ($parambreaktype && $parambreaktype.length() > 0)
#set ($varbreaktype = $parambreaktype)
#elseif ($param0 && $param0.length() > 0)
#set ($varbreaktype = $param0)
#else
#set ($varbreaktype = $defvarbreaktype)
#end
##
## Set pdfcontroltype value
#if ($varbreaktype == "KeepTogether")
#set ($pdfcontroltype = "pdfnobreakinside")
#elseif ($varbreaktype == "KeepwithPrevious")
#set ($pdfcontroltype = "pdfnobreakbefore")
#elseif ($varbreaktype == "KeepwithNext")
#set ($pdfcontroltype = "pdfnobreakafter")
#elseif ($varbreaktype == "ForceBreakBefore")
#set ($pdfcontroltype = "pdfbreakbefore")
#elseif ($varbreaktype == "ForceBreakAfter")
#set ($pdfcontroltype = "pdfbreakafter")
#end
##
## DISPLAY
## Debugging: Uncomment to display values
## defvarbreaktype=$defvarbreaktype
## varbreaktype=$varbreaktype
## pdfcontroltype=$pdfcontroltype
##
## Display Logic
<div id="pdfcontrolbreak" class="$pdfcontroltype">$body</div>
Notes:
- The macro needs to be converted to work with later versions of Confluence.
PDF CSS Settings for Page Breaks
In the PDF Stylesheet, I included the following CSS settings to stylize page break controls:
/* Widows and Orphans */
.widows {widows:2;}
.orphans {orphans:2;}
p, li {widows:2;orphans:2;}
/* CSS for Brute Force User Macros */
div.pdfbreakbefore {page-break-before:always;}
div.pdfbreakafter {page-break-after:always;}
div.pdfnobreakbefore {page-break-before:avoid;}
div.pdfnobreakafter {page-break-after:avoid;}
div.pdfnobreakinside {page-break-inside:avoid;}
/* Keep Together */
p {page-break-inside:avoid;}
/* Keep with Next */
.wiki-content h1, .wiki-content h2, .wiki-content h3, .wiki-content h4, .wiki-content h5, .wiki-content h6, .wiki-content h7, .wiki-content h8, .wiki-content h9, .wiki-content h10, .wiki-content h11, .wiki-content h12 {
page-break-after:avoid;}
/* Keep with Previous */
.image-wrap, div.expand-control {page-break-before:avoid;}
Notes:
- When inserting the page break tags, you cannot nest the tags; you must start and close a set before inserting another set.
- Typically, I add the “KeepwithPrevious” around content that should stay with the preceding paragraph, such as around an image or table that has an introductory sentence rather than a heading.
Example
In the following example, I applied the pdfcontrolbreak macro to an image I wanted to keep with the preceding paragraph.
h2. Simply a Filler about Cheese
{cheese}
h3. Roses
You can keep the following image with this text by using a PDF control break user macro.
{pdfcontrolbreak:breaktype=KeepwithPrevious}
!roses19.jpg!
{pdfcontrolbreak}
I applied the pdfcontrolbreak macro to a section I wanted to appear on a new page.
{pdfcontrolbreak:breaktype=ForceBreakBefore}
h2. Start on New Page
{pdfcontrolbreak}
{loremipsum}
When exported to PDF, the content looks like this:
Writing in the Cloud 