Page Breaks

The page breaks can be controlled in multiple ways:

By creating an @page and assigning it to an element will create a page break between this element and the sibling elements that have a different page.
Using the CSS properties: page-break-before, page-break-after, or page-break-avoid.
In your DITA topic, set the @outputclass attribute on the topic root (or any element) to contain one of the page-break-before, page-break-after, or page-break-avoid values. If you want to control the page breaking from the DITA map, use the @outputclass attribute on the <topicref>, with any of the values mentioned above.

Page Breaks - Built-in CSS

Page break properties are used in: [PLUGIN_DIR]css/print/p-page-breaks.css.

How to Avoid Page Breaks in Lists and Tables

To avoid splitting elements over two pages, you can use the page-break-inside CSS property. For example, if you want to impose this on tables and lists, then add the following rules to your customization CSS:

*[class ~= "topic/table"] {
    page-break-inside:avoid;
}
*[class ~= "topic/ol"] {
    page-break-inside:avoid;
}
*[class ~= "topic/ul"] {
    page-break-inside:avoid;
}

Note: Since the task steps are inherited from topic/ol, they will also not be split over two separate pages. However, if you want to allow this, add the following CSS rule:

*[class ~= "task/steps"] {
    page-break-inside:auto;
}

Note: Another way to do this is to mark the element with an @outputclass set to page-break-avoid.

Edit online

How to Force a Page Break Before or After a Topic or Another Element

If you want to force a page break before all the second-level topics (for example, sections in chapters that are usually kept flowing one after another without page breaks), add the following in your customization CSS:

*[class ~= "map/map"] > *[class ~= "topic/topic"] > *[class ~= "topic/topic"] {
	page-break-before:always;
}

If you need to break at third or fourth level topics, add more .. > *[class ~= "topic/topic"] selectors to the expression.

If you want to force a page break for a specific topic, mark the topic (or any other element you need to control page breaking for) with an @outputclass attribute set to one of these values:

page-break-before: Use this for a page break before the marked element.
page-break-after: Use this for a page break after the marked element.
page-break-avoid: Use this to avoid page breaks inside the marked element.

For example, to force a page break before a certain topic, use:

<topic outputclass="page-break-before" ... >

Note: You can set the output class on the <topicref> element from the DITA map instead of the <topic> element. In this way you can reuse the topic in another context where the page breaking is not necessary.

You can also control page breaking for lists, paragraphs, or any other block type elements. The following example avoids page breaks inside an ordered list:

<ol outputclass="page-break-avoid" ... >

Edit online

How to Add a Blank Page After a Topic

If you want to add a new blank page after a topic, add the following rules to your customization CSS.

Style the separating blank page:

@page topic-separating-page{
   @top-left {
     content: "";
   }
   @top-right {
     content: "";
   }
   @top-center {
      content: "This page is blank";
   }
}

Associate this page to the :after pseudo-element of the topic:


*[class~="topic/topic"][outputclass~="add-separator-page"]:after {
 content: " ";
 display: block;
 page: topic-separating-page;
}

In the XML content, on the <topic> element, set the @outputclass to the add-separator-page value.

<topic outputclass="add-separator-page"> ... </topic>

The :after pseudo-element will be created next to the topic content and will be placed on the topic-separating-page.

Use the page margin box selectors to override the default content from the headers/footers.

Note: You can set the output class on the <topicref> element from the DITA map instead of the <topic> element. This allows you to reuse the topic in another context where the page breaking is not necessary.

Edit online

How to Enforce a Number of Lines from Paragraphs that Continue in Next Page

In typography, an orphan is the first line of a paragraph that appears alone at the bottom of a page (the paragraph continues on a subsequent page), while a widow is the last line of a paragraph that appears alone at the top of a page. The default is 2 for each of them. You can control this number by adding the following to your customization CSS:

:root {
    widows:4;
    orphans:4;
}

Note: As a difference from the W3C standard, the widows and orphans CSS properties are applied to lists as well (the default is 2). This means that a list that spans consecutive pages will have either zero or at least 2 lines on each of the pages.

Edit online

How to Avoid Page Breaks Between Top-Level Topics (Chapters)

If you plan to publish a simple map with just one level of topics (such as a list of topics), then the automated page breaks between these topics might not be desired.

In this case, you can use the following CSS snippet to disable the page breaks between chapters:

*[class ~= "topic/topic"][is-chapter] {
  -oxy-page-group:auto; 
}