Wednesday, April 29, 2015

DITA PDF publishing - Force page breaks between two block elements

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Let's say that at some point in your DITA content you have two block level elements, like for example two paragraphs:
        <p>First para</p>
        <p>Second para</p>
and you want to force in the PDF output a page break between them.
Here's how a DITA Open Toolkit plugin which would achieve this could be implemented:
  1. You define your custom processing instruction which marks the place where a page break should be inserted in the PDF, for example:
            <p>First para</p>
            <p>Second para</p>
  2. In the DITA Open Toolkit distribution in the plugins directory you create a new plugin folder named for example pdf-page-break.
  3. In this new folder create a new plugin.xml file with the content:
    <plugin id="com.yourpackage.pagebreak">
      <feature extension="" value="Force Page Break Plugin"/>
      <feature extension="" value=""/>
      <feature extension="package.version" value="1.0.0"/>
      <feature extension="dita.xsl.xslfo" value="pageBreak.xsl" type="file"/>
    The most important feature in the plugin is that it will add a new XSLT stylesheet to the XSL processing which produces the PDF content.
  4. Create in the same folder an XSLT stylesheet named pageBreak.xsl with the content:
    <xsl:stylesheet xmlns:xsl=""
      <xsl:template match="processing-instruction('pagebreak')">
        <fo:block break-after="page"/>
  5. Install your plugin in the DITA Open Toolkit by running the DITA OT ANT integrator task.

    If you are running the publishing from Oxygen XML Editor you can use the predefined transformation scenario:

    If you run DITA OT from the command line please follow these guidelines:

The plugin code was also made available by Roger Sheen on GitHub:


  1. Worked perfectly! Thanks!

    1. Don, I'm confused about the dita-ot-install-plugin.html. Where is this file? I'm using Oxygen 16.1. Any advice is much appreciated! I'm not doing something right. I created the plugin and style sheet and added them into the plugin folder. I ran the DITA OT ANT scenario. Do I now need another scenario, dita-ot-install-plugin.html? Thanks, Evelyn

    2. Hi Evelyn,

      I see you already contacted us via email, we'll try to give you more details there.


  2. One more thing I wanted to add to this post, an issue about adding this kind of support for special processing instructions directly in the DITA Open Toolkit is opened here:

    As David Hollis mentioned there, if you want to keep elements on the same page, using "keep-within-next" is more appropriate.

  3. I have a similar situation for PDF output. We are using Keep-within-next to keep a graphic and the related text on the same page.
    Current tagging is:
    " Fig> Title> Info> Step>"

    The keep is in the stylesheet.

    Is there a way to to keep the graphic and more than one step on the same page?

    Fig> Title> Info> Step>"

    In the second scenario each step and the image should all appear on the same page in the majority of our content when outputted to PDF. Is there anyway to do this other than a page break?

    1. I don't understand, you seem to have a step inside an info inside a figure title. Maybe you can write about this on the DITA Users list and post a small DITA content sample.

  4. Does this work only for blocks within the same topic? How can I force a page break after the end of each topic in a map?

    1. This specif plugin only works to break block elements inside a topic. There is a suggestion about how to break pages between topics here: