The DITA Open Toolkit (DITA-OT) is the standard publishing engine for DITA content. Out of the box, it produces functional but generic output. Most organisations need to customise it to produce output that matches their brand, formatting requirements, and delivery channels.
Understanding the DITA-OT architecture
DITA-OT uses a plugin architecture: each output format is implemented as a plugin, and customisations are implemented as additional plugins that override or extend the base plugins. This architecture means that customisations can be kept separate from the base toolkit — which is essential for maintainability.
Never modify the base toolkit
The most common DITA-OT customisation mistake is modifying files in the base toolkit installation. This makes upgrades difficult or impossible. All customisations should be implemented as separate plugins that override specific behaviours.
PDF customisation with the PDF2 plugin
PDF output is typically the most complex DITA-OT customisation. The base PDF2 plugin uses Apache FOP as the formatting engine and XSL-FO as the intermediate format. Create a custom plugin that imports and overrides specific XSLT templates from the base PDF2 plugin.
HTML5 customisation
HTML5 output is generally simpler to customise than PDF. Keep styling in CSS and structural changes in XSLT. For organisations publishing HTML5 documentation to the web, integrating DITA-OT output with a static site generator can provide better navigation and user experience.
Version control and CI/CD integration
DITA-OT customisations should be version-controlled alongside your DITA content. Integrate DITA-OT builds into your CI/CD pipeline so that output is generated automatically on every content change — this catches publishing errors early and ensures published output is always current.
Upgrading DITA-OT
DITA-OT releases regularly. If your customisations are implemented as proper plugins rather than modifications to the base toolkit, upgrades are straightforward: install the new version, install your plugins, and test.
Well-structured DITA-OT customisations are maintainable, upgradeable, and reliable. The investment in doing it right pays back every time you need to upgrade the toolkit or add a new output format.