DITA Open Toolkit 3.6 Release Notes

DITA Open Toolkit 3.6.1 is a maintenance release that fixes issues reported in DITA-OT 3.6, which includes performance enhancements such as processing in parallel and in memory, support for PDF changebars with Apache™ FOP, and an updated preview of features for the latest draft of the upcoming DITA 2.0 standard, including the <audio> and <video> elements, and the new emphasis domain.

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.6.1.zip package from the project website at dita-ot.org/download.


DITA-OT is designed to run on Java version 8u101 or later and built and tested with the Open Java Development Kit (OpenJDK). Compatible Java distributions are available from multiple sources:

DITA-OT 3.6.1

DITA Open Toolkit 3.6.1 is a maintenance release that includes the following bug fixes.

  • In DITA-OT 3.6, builds failed with a NullPointerException when Ant targets in custom <pipeline> elements were run without passing references to the new Ant project by setting the @inheritRefs attribute on the <antcall> to true. This case will no longer cause the build to fail, but custom plug-ins should still set targets to inherit references to ensure that processing runs as expected. #3656, #3657
  • The jsass compiler used in the HTML5 plug-in build process up to DITA-OT 3.6 relied on LibSass, which has been deprecated in favor of Dart Sass and caused errors when building on the 64-bit extension of the ARM architecture. The SCSS source files are now converted to CSS using the official Dart Sass compiler, which allows DITA-OT distribution builds to run on recent Macs and other ARM systems. #3659
  • In DITA-OT 3.6, builds failed with a NullPointerException when an unset logger was called. A new guard has been added to handle these cases more gracefully. #3667, #3706
  • The DOTX037W warning message that appears when source documents have no title has been updated to clarify references to the fallback text that will be used for the HTML page title. #3669, #3670
  • DITA-OT 3.6 failed with an IllegalArgumentException when maps contained topic references to e-mail addresses or other peer resources that are not accessible at build time. Processing has been updated to properly handle non-file references. #3677, #3698
  • In DITA-OT 3.6, branch filtering with nested subtopics failed with an IllegalArgumentException: URI has a fragment component. Processing has been updated to correctly transform references that contain anchors. #3680, #3696
  • DITA-OT 3.6 in-memory processing calculated absolute paths incorrectly when merging maps. The merge map and topic parsers have been updated to properly compute absolute locations. #3687, #3699
  • DITA-OT 3.6 introduced a regression that prevented PDF2 custom font mappings from resolving properly. The PDF pre-processor task has been updated with a delegating URI resolver to ensure that custom resources in PDF plug-ins are applied as expected. #3688, #3695
  • Custom rules used to adjust the names and locations of output files in the map-first pre-processing routine were no longer applied in DITA-OT 3.6. Preprocessing has been updated to ensure that stylesheets specified via the result.rewrite-rule.xsl parameter are correctly applied. #3689, #3697
  • In DITA-OT 3.6, a regression prevented multi-level key references from resolving properly. Processing has been updated to ensure that topic metadata is correctly copied between key definitions and key references that point to other keys. #3694, #3701
  • The GitHub Packages Docker registry used to publish DITA-OT Docker images prior to version 3.6 has been superseded by the GitHub Container Registry. The new registry offers anonymous access to public container images, so you can use it without a GitHub account. As of DITA-OT 3.6.1, the official image is published to the new registry at ghcr.io. If you’ve pulled from docker.pkg.github.com/dita-ot/dita-ot/dita-ot:version in the past, update your workflow to pull from ghcr.io/dita-ot/dita-ot:version instead.
  • The DITA-OT project now provides an official dita-ot-action that can be used to publish documentation via GitHub Actions whenever your source files are changed.
  • The documentation for DITA Open Toolkit Release 3.6.1 provides corrections and improvements to existing topics, along with new information in the following topics:

For additional information on the issues resolved since the previous release, see the 3.6.1 milestone and changelog on GitHub.

DITA-OT 3.6 released December 19, 2020

DITA Open Toolkit Release 3.6 includes performance enhancements such as processing in parallel and in memory, support for PDF changebars with Apache FOP, and an updated preview of features for the latest draft of the upcoming DITA 2.0 standard, including the <audio> and <video> elements, and the new emphasis domain.

Parallel processing

Preprocessing module code can now be run in parallel by setting the parallel parameter to true. The performance benefits this option provides depend heavily on the source file set, the DITA features used in the project, and the computer doing the processing, but under the right circumstances, you may see notable improvements when this option is enabled.

In-memory processing

DITA-OT 3.6 introduces a new Store API with preview support for in-memory processing. The Cache Store can be activated by setting the store-type parameter to memory. In-memory processing provides performance advantages in I/O bound environments such as cloud computing platforms, where processing time depends primarily on how long it takes to read and write temporary files. For more information, see Store API – Processing in memory.

Additional performance improvements

DITA-OT 3.6 includes a series of related changes designed to improve the performance of DITA transformations.

  • A new --repeat option can be passed to the dita command to run the process a certain number of times. This option can be used by plug-in developers to measure performance. (Timings for the first transformation are often dominated by Java warm-up time.) #3616

    To run a conversion five times, for example, use --repeat=5. The duration of each execution will appear in the console when the final transformation is complete.
    $ dita --input=docsrc/samples/sequence.ditamap --format=html5 --repeat=5
    1 11281ms
    2 4132ms
    3 3690ms
    4 4337ms
    5 3634ms
  • The DITA-OT Java code uses a new caching DitaClass.getInstance(cls) factory method rather than generating DitaClass instances directly. This allows previously created instances to be re-used, which reduces the number of instances that need to be created. #3569
  • The Java code for several preprocessing modules has been refactored to use concurrent sets or queues. This helps to speed up certain operations during preprocessing, allowing builds to complete faster. #3570
  • The Java code now uses a BufferedWriter to serialize Job objects, which significantly improves UTF-8 encoding performance when writing the .job.xml file. #3583

PDF changebars with Apache FOP

For DITA-OT 3.4, the bundled Apache™ Formatting Objects Processor library was upgraded to version 2.4, which included support for changebars, but those features were not yet enabled in DITA-OT 3.4 pending further testing. DITA-OT 3.6 removes the FOP-specific overrides that disabled changebars in earlier versions, allowing the default PDF2 flagging routines to be applied when generating PDFs with FOP. For details, see Generating revision bars.

Plug-ins that implemented custom FOP flagging by overriding the org.dita.pdf2.fop/xsl/fo/flagging_fop.xsl stylesheet in prior versions will need to be updated, as this file is no longer available in DITA-OT 3.6. #3511, #3591

Updated DITA 2.0 preview

In addition to the DITA 2.0 preview support provided in DITA-OT 3.5, this release includes updated processing support for the latest DRAFT versions of the DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of October 2020). #3586, #3601, #3617, #3652

  • Where earlier DITA versions relied on the <object> to embed media in DITA source files, DITA 2.0 provides new <audio> and <video> elements that correspond to their HTML5 equivalents.
  • For HTML5 compatibility, the new emphasis domain adds support for the <strong> and <em> elements in addition to the existing <b> and <i> elements in the highlighting domain.
  • The troubleshooting domain has been updated with additional constructs that can be used to provide detailed diagnostic information.
  • Several obsolete elements and attributes have been removed from DITA 2.0, including:
    • <boolean>
    • <data-about>
    • <indextermref>
    • @alt on <image>
    • @navtitle on <topicref>
    • @query on <topicref>
    • @refcols on <simpletable>
    • @xtrc
    • @xtrf

DITA documents that reference the draft grammar files can be parsed, and where features overlap with DITA 1.3, those features will work as expected.

Note: Other new or revised features proposed for DITA 2.0 are not yet supported. Additional features will be implemented in future versions of DITA-OT as the specification evolves.

Enhancements and changes

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

  • The @rotate attribute on table <entry> elements is now respected when generating HTML5 output. The rotation is implemented by setting the CSS writing-mode property to vertical-rl to rotate the cell content. This property is rendered correctly in Mozilla Firefox, but unevenly supported by other browsers. The rotate class is passed to HTML5 output, so custom plug-ins can implement alternative presentation rules in CSS if necessary. #3448, #3541, #3651
  • User-facing text for the dita command line interface has been extracted to a strings file to facilitate editing. The cli_en_US.properties is provided in the resources folder as a basis for customization and localization. #3495, #3523
  • The new Store implementation that supports in-memory processing includes an immutable document reader method that can be used to request a document that doesn't need to change during processing. This approach facilitates caching and helps to speed up processing. #3506, #3548
  • In earlier versions, variations in reference capitalization could cause unexpected results when building output on case-sensitive file systems. DITA-OT now warns when file references use incorrect case. (For example, if maps reference Topic.dita, but the filename on disk is actually topic.dita.) In strict processing mode, this is considered a fatal error; in lax processing mode, the file reference is rewritten to use the same case as the file system. #3535
  • The --filter option can now be passed to the dita multiple times in a single command-line invocation to apply conditions from several DITAVAL files at once. #3556
  • The bundled Apache Formatting Objects Processor (FOP) has been upgraded to version 2.5, which includes security updates to various embedded libraries. #3558, #3630
  • The deprecated msgprefix XSL variable (“DOTX”) has been removed. This variable was originally deprecated in DITA-OT 2.3, but still defined in several stylesheets. Importing the common XSL module output-message.xsl no longer requires this variable to be defined. #3562
  • The S9api message listener from the Saxon API is now used to forward log messages to the DITAOTLogger. This allows message levels and error codes to be passed from XSLT to Java code for improved debugging. #3564
  • HTML5 output now includes additional metadata to indicate that the content was produced using DITA Open Toolkit. #3594
    <meta name="generator" content="DITA-OT"/>
  • Up to version 3.5, DITA-OT included the Dublin Core Metadata Element Set in both XHTML and HTML5 output. For DITA-OT 3.6, this capability was extracted to a separate plugin, and Dublin Core metadata is no longer generated in the default HTML5 output. #3595

    If necessary, the org.dita.html5.dublin-core plug-in can be installed from the plug-in registry at dita-ot.org/plugins to add Dublin Core metadata to HTML5. To install the plug-in, run the following command:

    dita install org.dita.html5.dublin-core
  • In XHTML output, previous versions failed to distinguish Notice note types from regular notes, prefixing both with Note. Support has been backported from HTML5 to XHTML to prefix notices with Notice as expected. #3599, #3600
  • Unused code for flagging and key processing has been removed along with related files that have been deprecated since version 2.1, including the base flag.xsl stylesheet, the generated keydef.xml file, and schemekeydef.xml. #3602, #3603
  • Remaining inline style attributes were removed from HTML5 code, which prevented custom plug-ins from overriding the presentation of the corresponding elements, including:
    • <line-through> and <overline> elements
    • syntax diagrams
    • long quote citations
    • Boolean states

    These changes move the default presentation rules to CSS to allow users to override these styles in custom stylesheets. The output is visually equivalent to the results generated by previous toolkit versions. #3632

    Important: In publishing environments that do not use the default common CSS files, these styles may need to be implemented in custom stylesheets.


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

  • Folder names in development build archives previously included the “+” plus sign, which caused errors when running from the unpacked directory. The snapshot folder name syntax has been updated to use the “@” at sign instead, which allows builds to run directly from the extracted folder. #2414, #3623

  • The license text for the beta DITA 2.0 grammar file plug-in was missing in DITA-OT 3.5 and is now included in the distribution package. #3608, #3649

  • The Java code has been refactored to anticipate cases where resources are missing or incorrectly defined.
    • The File.toURI() method has been updated to ensure that the generated URI for a directory will always end in a trailing slash. This prevents unexpected errors in cases when the File input points to a path that doesn’t exist. #3621, #3624, #3626
    • The JobSourceSet has been fixed to handle cases where the src input is null. #3625
  • In DITA-OT 3.5.4, the HTMLHelp stylesheet map2hhcImpl.xsl included an invalid code remnant left over from previous edits. The unnecessary line has been removed. #3627, #3634


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

  1. Jarno Elovirta
  2. Roger Sheen
  3. Robert D Anderson
  4. Radu Coravu
  5. David Bertalan

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.6 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.6, see the 3.6 milestone in the documentation repository.

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

  1. Roger Sheen
  2. Jarno Elovirta
  3. Lief Erickson
  4. Heston Hoffman

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