Force Page Breaks Between Two Block Elements in PDF Output

Suppose that in your DITA content you have two block elements, such as two paragraphs:

<p>First para</p>
<p>Second para</p>

and you want to force a page break between them in the PDF output.

Here is how you can implement a DITA Open Toolkit plugin that would achieve this:

1. Define your custom processing instruction that marks the place where a page break should be inserted in the PDF, for example:

   <p>First para</p>
     <?pagebreak?>
   <p>Second para</p>

2. Locate the DITA Open Toolkit distribution and in the plugins directory create a new plugin folder (for example, DITA-OT-DIR/plugins/pdf-page-break).
3. In this new folder, create a new plugin.xml file with the following content:

   <plugin id="com.yourpackage.pagebreak">
     <feature extension="package.support.name" value="Force Page Break Plugin"/>
     <feature extension="package.support.email" value="support@youremail.com"/>
     <feature extension="package.version" value="1.0.0"/>
     <feature extension="dita.xsl.xslfo" value="pageBreak.xsl" type="file"/>
   </plugin>

   The most important feature in the plugin is that it will add a new XSLT stylesheet to the XSL processing that produces the PDF content.

4. In the same folder, create an XSLT stylesheet named pageBreak.xsl with the following content:

   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                         xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
     <xsl:template match="processing-instruction('pagebreak')">
       <fo:block break-after="page"/>
     </xsl:template>
   </xsl:stylesheet>

5. Install your plugin in the DITA Open Toolkit.