Customizing the First Page of a Chapter

This topic describes how to change the layout of the first page of a chapter.

By default, the DITA-OT PDF plugin generates the chapter's first page with this layout:

The first two lines present a static Chapter label followed by the chapter's number. The chapter's title is displayed on the next line and then the remaining space is divided into two columns. The first column presents the links to all the topics in the chapter (this area is known as MINITOC). The second column presents a summary of the chapter.

For our customization, we simplified the first part of the page to present the chapter's title and its number on a single line followed by a thin separator line. Also, we changed the presentation for the chapter's MINITOC and description to present them in separate blocks, one after another, in a single column as in the following image:

To implement these requirements, we needed to override some XSLT templates that are responsible for the layout of the chapter's first page. All of these templates are defined in the DITA-OT-2.4/plugins/org.dita.pdf2/xsl/fo/commons.xsl file. Thus, we created a similar XSLT stylesheet in the plugin's customization folder with this path: com.oxygenxml.pdf2.ug/Customization/fo/xsl/commons.xsl. This is a convention that helps you to identify the original file from where the templates were copied in case you want to change them or you encounter issues in the future.

The XSLT templates that should be overridden to accomplish this task are as follows:

• <xsl:template match="*" mode="insertChapterFirstpageStaticContent">

  The default implementation of this template generated the static Chapter label and the chapter's number on separate lines. For our customization, this template was changed to generate only the chapter's number.

• <xsl:template name="processTopicChapter">

  This is the template that process the entire chapter. For our customization, we changed the first part of the template that is associated with chapter's title and number to generate a table with one row and two cells. The first cell renders the chapter's title and the second renders its number. Similarly, we overrode other XSLT templates (processTopicNotices, processTopicAppendix, and processFrontMatterTopic) because they are used for top level topics such as notices or appendix that are used in a DITA bookmap and these types of topics are rendered similarly to a chapter's first page.

• <xsl:template match="/*" mode="createMiniToc">

  This template is used to generate the MINITOC area. In the left column, the links to chapter's topics are presented and the chapter's content is presented in the right column.

  For our customization, we changed this template to generate both areas, one after another, in a single column.

You can see all of these changes in the GITHUB project associated with this customization: com.oxygenxml.pdf2.ug/Customization/fo/xsl/commons.xsl.