DITA Publishing Customization Overview

Read time: 8 minute(s)

Oxygen XML Editor publishes DITA content to various output sources using a bundled version of the DITA Open Toolkit (short name: DITA OT) publishing engine. Oxygen versions prior to version 20 come with two DITA OT versions:

DITA OT 1.8 located in the OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT folder.
DITA OT 2.x located in the OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x folder.

while Oxygen version 20 comes bundled only with DITA OT 2.x located in the folder specified above. You can find the exact version of DITA OT bundled with Oxygen by looking in the main menu Help->About at the Frameworks tab.

DITA Open Toolkit Overview

The DITA Open Toolkit is an open source publishing engine that can publish DITA content to various output sources such as XHTML, PDF, or Windows Help (CHM). Since it has a plugin-based architecture, it can be extended with extra plugins that either define new formats for conversion or customize an existing conversion format. You can run the DITA OT from Oxygen using its transformation scenarios or you can run it directly from a command line:http://www.dita-ot.org/dev/topics/building-output.html.

The DITA OT bundled with Oxygen contains more plugins than the standard DITA OT that can be downloaded from the DITA OT official web site. For example, it contains pre-installed plugins for converting DITA content to Word, EPUB, Oxygen WebHelp, or to publish to PDF using CSS to customize the output: Useful DITA OT Plugins.

Publishing Customizations (Before you begin)

Some customizations, usually for HTML-based output, can be made simply by creating a custom CSS and they do not involve modifying the DITA OT engine in any way. But most customizations might involve adding a new plugin to the DITA OT. So here are some best practices before you begin your customization:

Copy the bundled DITA OT folder (usually OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT2.x) to a location outside of Oxygen. This will allow you to have full write access to the folder in order to install new plugins:https://www.oxygenxml.com/doc/ug-editor/topics/dita-ot-install-plugin.html.
In the Oxygen Preferences->DITA page, set the default DITA OT distribution to be the external copied one. This will mean that Oxygen will use the external DITA OT for DITA validation and publishing. After doing this, you will be able to upgrade the Oxygen version and benefit from all editing-related improvements without affecting the publishing system.
Share that external DITA OT copy with the rest of the team. If you are using a repository like Subversion or Git for collaboration, you can commit the entire modified DITA OT publishing engine as part of your project. This will allow everybody else in your team to use the official changes that you made. This will also allow you to set up some kind of automatic publishing system using an open-source integration server like Travis.

Customizing the XHTML-based outputs

Usually XHTML-based outputs can be modified by using a custom CSS stylesheet to override various styles. If you edit an XHTML-based transformation scenario in Oxygen, there is a parameter called args.css that can be set to point to your custom CSS and a parameter called args.copy.css that can be set to yes to copy the CSS to the output folder. To know what CSS styles to override, you can use your web browser’s CSS Inspector tools to look at the produced HTML output. The same parameters can be set when publishing from a command line: http://www.dita-ot.org/dev/topics/html-customization-css.html.

You can also create plugins to customize the XHTML-based outputs by adding an extra XSLT stylesheet: for example, Creating a simple DITA Open Toolkit plugin to customize published HTML and PDF content. A list with all DITA OT XSLT extension points can be found here: http://www.dita-ot.org/dev/extension-points/plugin-extension-points-xslt-import.html.

Customizing the Oxygen WebHelp-based output

Oxygen’s DITA OT comes bundled with specific plugins developed by Oxygen that allows publishing DITA content to WebHelp Responsive output. Oxygen’s User’s Guide has detailed topics about how to customize these outputs: https://www.oxygenxml.com/doc/ug-editor/topics/wh-responsive-customization-tips.html.

Customizing the PDF Classic output

The DITA to PDF output can be customized either by creating a PDF customization folder (in this case the DITA OT folder will not be modified at all) or by creating a PDF customization plugin: https://www.oxygenxml.com/doc/ug-editor/topics/dita-pdf-output.html. There is also a book called DITA For Print that contains details about how to customize various aspects.

Customizing the DITA + CSS to PDF output

In recent versions, Oxygen added a new transformation scenario called DITA Map PDF - WYSIWYG that allows you to use CSS to style the PDF output, lowering the required knowledge for implementing a PDF customization. There is an entire chapter in the Oxygen users manual covering various PDF customization details: https://www.oxygenxml.com/doc/ug-editor/topics/dcpp_the_customization_css.html#dcpp_the_customization_css.