DITA Open Toolkit 3.1 Release Notes

DITA Open Toolkit 3.1 is a feature release that provides new features and enhancements, including support for DITA 1.3 SVG domain elements, enhanced <codeblock> processing, and incremental improvements to Lightweight DITA processing and PDF output.

DITA-OT releases follow semantic versioning guidelines. Version numbers use the major.minor.patch syntax, where major versions may include incompatible API changes, minor versions add functionality in a backwards-compatible manner and patch versions are maintenance releases that include backwards-compatible bug fixes.

Tip: Download the dita-ot-3.1.zip package from the project website at dita-ot.org/download.


DITA Open Toolkit Release 3.1 requires the Java Runtime Environment (JRE) version 8 or later.


DITA Open Toolkit Release 3.1 includes support for DITA 1.3 SVG domain elements, enhanced <codeblock> processing, and incremental improvements to Lightweight DITA processing and PDF output.


DITA Open Toolkit Release 3.1 includes the following new features:

  • A new Java wrapper for the XSLT mapref map resolution module allows for better handling of content references and key references in nested maps. #2875
  • Updates to the Java code that calls Saxon now support integrated extension functions for Saxon HE (versions ≥ 9.2). #2880
  • A new end-to-end test case ensures a basic test is run for all supported transformation types with every update to DITA-OT. #2932
  • DITA-OT now supports the DITA 1.3 SVG domain elements, including <svgref> for pulling in external SVG markup. #2960
  • PDF output now supports key-based linking for phrase like elements, including <cite>, <ph>, and <dt>. When key definitions specify a URI for linking, the links will now appear in PDF. This markup already resulted in links in HTML output, and resulted in PDF links for key references on <keyword> and <term>. #2025, #2961
  • Processing for <codeblock> elements has been enhanced to support new @outputclass keywords that can be used to adjust the presentation of code samples.
    • To remove leading whitespace in external code references, set the @outputclass attribute to include the normalize-space keyword. With this setting, DITA-OT trims any leading whitespace that is common to all lines in the code block to remove excess indentation and keep lines short. #2907, #2953
    • To highlight whitespace characters in code blocks, set the @outputclass attribute to include the show-whitespace keyword. When PDF output is generated, space characters in the code will be replaced with a middle dot or “interpunct” character ( · ); tab characters are replaced with a rightwards arrow and three spaces ( →    ). #2975
    • To add line numbers to code blocks in PDF output, set the @outputclass attribute to include the show-line-numbers keyword.
      Note: Line numbering has been available since DITA-OT 2.0, but previously required custom PDF plug-ins to override the codeblock.generate-line-number template mode to return true(). DITA-OT 3.1 now checks for the keyword in the @outputclass, so line numbering can be enabled without custom PDF plug-ins.

Enhancements and changes

DITA Open Toolkit Release 3.1 includes the following enhancements and changes to existing features:

  • The error message generated for duplicate key definitions has been updated for clarity. #2079
  • Ant scripts for DITA-OT builds now make use of @if:set and @unless:set attributes in the Ant namespace, which can be used to control whether parameters are passed to XSLT modules. These attributes replace custom implementations of if and unless logic introduced before Ant had this capability. #2890
  • The PDF build code has been refactored and simplified to use the <xmlcatalog> element instead of using a custom xml.catalog.files property. #2938
  • Alternate text for images is now preserved in the XSL-FO files generated for PDF, using the custom attributes necessary for Apache™ FOP, RenderX XEP, and Antenna House processors. The alternate text is now available in the final output file when processors generate accessible PDF. #2850, #2964
  • In PDF processing with Apache FOP, DITA-OT 3.1 now uses the Simple Logging Facade for Java (SLF4J), allowing for better control and formatting of FOP log messages. To reduce noise on the console, all FOP messages are set to the Info level and hidden by default. #2967
  • The HTML5 XSLT stylesheets used to create TOC navigation have been refactored to use a new processing mode. This removes the "Duplicate import of map2html5Impl.xsl" message that appeared with DITA-OT 3.0. #2821 #2970
  • The distribution build has been updated to use the documentation Gradle build instead of Ant. #2972
  • The bundled Apache FOP version has been updated to 2.3. (For details on recent changes, see the Apache FOP 2.3 Release Notes.) #2974, #2976
  • The @frame attribute on <choicetable> elements is now respected in PDF output; previously all values for @frame on this element were ignored in PDF. #2978
  • The LwDITA plugin has been updated to version 2.0.5, pulling in a number of fixes for Lightweight DITA processing. (Topic metadata is now preserved in YAML headers when generating Markdown for composite topics, autolinks in Markdown topics are treated as external cross references, and definition lists in Markdown input and links to ID fragments are now handled correctly.) #2982, #2993
  • PDF processing now includes a hook that can be used to add custom <fo:marker> elements on any topic. New processing hooks are also available to add custom anchors on any topic or titled sub-topic element, intended as a way to enable stable links into a location within a PDF. #2984
  • The Gradle wrapper used to run the documentation build has been updated to version 4.8. #2991, #2994


DITA Open Toolkit Release 3.1 provides fixes for the following bugs:

  • When a nested map uses @conref to pull content from another map, but the root map does not use @conref, the content reference was not previously resolved. This is now fixed, and content references in all maps used by the build are resolved properly. #2494
  • When a <chapter> element refers to another map that is not a bookmap, PDF processing now formats the referenced content as a chapter. In earlier versions, the content could be formatted as a generic topic that did not match other chapters in the same map. #2898
  • The error message DOTJ007E, which appeared for duplicate filter conditions in DITAVAL properties, has been switched from an Error to a Warning. This message, which usually does not indicate a problem that results in broken output, will now appear as DOTJ007W. #2958
  • The empty temp/ directory included in DITA-OT 3.0 distribution packages has been removed. #2973
  • Several duplicate ID messages that appeared in PDF processing have been fixed by removing incorrect ID definitions. These messages could previously appear when nested elements inside of topic titles or topic short descriptions specified their own @id attribute; in DITA-OT 3.0, this also appeared for all <pt> elements that specified @id. #2985
  • Several unnecessary files have been removed from the docsrc/ folder of the distribution package. #2990


DITA Open Toolkit Release 3.1 includes code contributions by the following people:

  1. Jarno Elovirta
  2. Robert D. Anderson
  3. Roger Sheen
  4. Radu Coravu
  5. Alexey Mironov
  6. Stefan Eike
  7. Shane Taylor

For the complete list of changes since the previous release, see the changelog on GitHub.

Documentation updates

The documentation for DITA Open Toolkit Release 3.1 provides corrections and improvements to existing topics, along with new information in the following topics:

For additional information on documentation issues resolved in DITA Open Toolkit Release 3.1, see the 3.1 milestone in the documentation repository.

DITA Open Toolkit Release 3.1 includes documentation contributions by the following people:

  1. Roger Sheen
  2. Robert D. Anderson
  3. Lief Erickson
  4. Stefan Eike
  5. Jarno Elovirta
  6. Eero Helenius
  7. François Violette

For the complete list of documentation changes since the previous release, see the changelog.