Tridion Docs PDF Customizations – DITA-OT, Style and Design

In the first installment of the Tridion Docs PDF Customizations blog series, we discussed how to publish content as downloadable formats. Today, we’ll cover a few of the most important design and presentation customization aspects to apply company branding to that content by tailoring the DITA-OT publishing engine in Tridion Docs.

Corporate branding establishes uniformity and provides a visual identity that’s unique to your company or product. That consistency is critical in today’s business and applies to everything from presentations to official documents. Publishing PDF documents from Tridion Docs is no exception and the design and visuals must align with your company’s branding.

Part 1 | DITA-OT

Before moving on to presentation customizations, it’s important to understand the rendering process of a PDF document when publishing it from Tridion Docs.

In Tridion Docs, content is authored in DITA (Darwin Information Typing Architecture). DITA is an XML content authoring standard owned and developed by OASIS. Generally, to render the DITA content into different publishing types like PDF, HTML based formats, and Markdown, etc., DITA Open Toolkit (DITA-OT) is used.

DITA Operational Toolkit (DITA-OT) is the plugin-based engine responsible for the processing of the published DITA content. In Tridion Docs we have an extended DITA-OT named “infoshare” which can be found at “\Infoshare\App\Utilities\DITA-OT\InfoShare” on the CMS Server.

It has some additional Tridion Docs specific plugins inside the “plugins“ directory. The “ishPdf” plugin is responsible for the publishing of PDF documents as shown in the figure below:

When a user publishes the publication to a PDF output format:

DITA-OT merges all the DITA content inside the publication and creates a merged XML file.
ishPdf processor steps are then applied to the merged XML and it is converted intermediate XSL-FO (XSL Formatting Objects) file. (XSL-FO is a markup language for XML document formatting that is most often used to generate PDF files)
The XSL-FO file is then picked by an XSL-FO processor which converts it to a PDF document. Tridion Docs uses a product named “Antenna House” as an XSL-FO processor which is shipped with Tridion Docs.

To apply a company’s branding, we must customize the plugin “ishPdf” of the DITA-OT “infoshare”. As described in the next section, before making updates to the ishPdf plugin, it’s recommended to create a company-specific DITA-OT (and plugins) workspace.

Setup the Custom DITA-OT

Generally, to avoid interference with the OOB supplied code, we create our customization workspace. Tridion Docs provides an “infoshare” DITA-OT publishing engine tailor-made for Tridion Docs publishing. Below are the steps to create a custom DITA-OT based on “infoshare” DITA-OT.

Create a duplicate folder of “infoshare” at the same location and rename it. We’ll use “Contentbloom”.
Update the “\InfoShare\Web\Author\ASP\ClientConfig\metadataConfig.xml” by adding a StyleProcessor by merging the element below:

<ishfrmfield id="StyleProcessorField" name="StyleProcessorField" ishfieldref="FSTYLEPROCESSOR" level="none">
   <typepulldown>
      <valuelist>
        <enumlist>
        <item>
            <value>DITA-OT\Contentbloom</value>
            <label resourceref="FSTYLEPROCESSOR.ValueList.DITA-OT-CONTENTBLOOM.Text">Contentbloom-OT</label>
        </item>
        </enumlist>
      </valuelist>
    </typepulldown>
<ishfrmfield>

Restart the app pool of the website.

After the above process, the “Contentbloom -OT” style processor would be available in the Output Format properties. Select it in the Output Format properties you want to use for PDF publishing.

Now that we are done with setting up our custom DITA OT processor, we are all set to customize the style and design to implement our company-specific branding.

Part 2 | Style and Design

As a quick recap, we learned above that we need to update the DITA-OT plugin named “ishPDF” to apply a company’s branding and it’s important to set up a custom DITA-OT before we start doing customizations to style and design for it. The ishPDF plugin to be updated is located at the path below:

“\Infoshare\App\Utilities\DITA-OT\Starbucks\plugins\ishPdf”

Let’s dive into how to customize the PDF presentation to apply company branding. We can divide the customizations into the three parts as explained below.

1. Style Customizations

This is like applying the CSS stylesheet to an HTML markup. In this case, we define the styles to be applied to the XSL-FO markup before converting it to PDF. You can define your custom styles using the template files placed at the path “\xsl\templates” inside the ishPdf plugin.

infoshare.templates.xml:

This file defines the template filenames for the different output formats. Below is the out of the box version of the file. You can add a new entry for additional output formats but if you want to customize existing output format styles you don’t need to update this file.

For example, if you want to customize the “pdf (letter manual)” output format, you can make changes directly to “infoshare.template.letter.xml” template file. I recommend taking a backup of the file before the updates to it. Each template file has three sections page-setup, styles, and fonts where you can find child nodes controlling different aspects related to parents.

Page Setup

As the name suggests, this section controls the setup of the pages in a PDF document. As you can see in the image, all the entries are self-explanatory. If you want to change images for background image or logo, please upload the images to the folder “\ishPdf\resources” before updating the filenames in the template file.

Styles

This section is used to define the styles for Body elements like P, Headings, Hyperlinks, and Li, etc. The element names are quite like the CSS Stylesheets. In this section, text fonts, spacing, colors, etc. could be controlled for the elements.

Fonts

The font section has elements to define the default fonts and preferences for the elements in different languages.

2. Design Customizations

To customize the design or layout of the PDF pages, the XSLT files responsible to render the XSL-FO files need to be updated. These files could be found inside the ishPdf plugin at the path “\xsl\xslfo”. There are many files responsible for rendering different parts of the XSL-FO file. For example, “infoshare.dita2fo.setup.xsl” is used for the general setup of the layout of the document whereas “infoshare.dita2fo.toc.xsl” controls the rendering of the table of content (TOC) section.

For instance, if company branding requires to present the TOC in a specialized manner, the infoshare.dita2fo.toc.xsl file needs to be updated accordingly.

Sometimes you’ll need to add new style elements in the style templates (as explained in the previous section). Later these styles must be referenced to the right elements in the XSLT files, otherwise the styles will be not be reflected after the publishing process.

3. Labels

In addition to the above two points, you can also customize the various labels used in the rendering process for different languages. Many labels are not author-controlled and appear in the published content. For example, the TOC page heading “Table of Contents”. Similarly there are so many other labels coming from the language-specific resource files found at “\ishPdf\xsl\resources”. There are many files with the name strings {lan}.xml where {lan} is the language. These resource files have key-value pairs defining the labels. The existing values can be updated and the new key-value pairs could be added if needed.

So far, we’ve covered most of the foundational knowledge about PDF customizations in Tridion Docs, however, it’s risky to update files and publish without verifying the results. This approach could work for minor changes and quick fixes, but when it comes to to implementing your company’s branding, a local development environment is needed to allow developers the freedom to update and preview results within a staging environment without publishing to live. Once the updated files produce the desired results, they could then be deployed to the CMS server.

There are multiple ways to set up a local DITA-OT development environment using different tools. I recommend using Oxygen for it. Once the setup is done, the published merged XML file from the CMS server could be used as input for the debugging and verification process.

Stay tuned for the last installment of the Tridion Docs PDF Customizations blog series!

Tridion Docs PDF Customizations – DITA-OT, Style and Design