DITA Open Toolkit 3.4 Release Notes

DITA Open Toolkit 3.4.1 is a maintenance release that fixes issues reported in DITA-OT 3.4, which includes an official Docker container image, a separate plug-in for PDF indexing, a new option to skip HTML5 cover pages, and initial support for project files that allow you to define multiple deliverables in advance, and publish them all at once.

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.4.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.4.1

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

  • Earlier versions of DITA-OT created extra files in the output folder when the DITA 1.3 <dvrResourcePrefix> or <dvrResourceSuffix> elements were used to rename filtered topics. When conditions on topic references within a branch filtered out one or more copies of those files, the renamed resources were removed from the ToC, but still copied to the output folder. The branch filtering process has been revised to ensure those filtered copies are no longer created. In some (but not all) cases, this also resolves a related issue where an extra copy of the file was created in the output folder with the original file name. #2980, #3411
  • Due to an omission in the DITA 1.3 shell files provided by the OASIS DITA Technical Committee, classification maps based on the XML Schema Definition were considered invalid. The error was reported to the TC and resolved in the official OASIS repository and in the grammar files bundled with DITA-OT. #3202, #3426
  • The RELAX NG schema required to validate XML project files was missing in the 3.4 distribution package. The project.rnc file is now provided in the resources folder of the DITA-OT installation. #3409, #3410
  • When the bundled Apache™ Formatting Objects Processor (FOP) was upgraded to version 2.4 for DITA-OT 3.4, a required library reference was omitted, which prevented embedded SVG images from appearing in PDF output. The library has been restored to the distribution package to ensure that SVGs are rendered as expected. #3414, #3419
  • The bundled Jackson data binding library was updated to version 2.10.1 to resolve several vulnerabilities reported in previous versions. #3420, #3421
  • With DITA-OT 3.1.3 or later, generating PDFs from maps with index terms with the RenderX XEP processor throws “no entries for index key” errors and fails to generate PDF files. Index processing has been corrected to take the new @indexid attribute into account, which resolves the error and allows builds to complete successfully. #3447, #3450, #3455
  • The license for the bundled ICU4J library has been updated to the latest version. #3444, #3451, #3454

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

DITA-OT 3.4 released November 9, 2019

DITA Open Toolkit Release 3.4 includes an official Docker container image, a separate plug-in for PDF indexing, a new option to skip HTML5 cover pages, and initial support for project files that allow you to define multiple deliverables in advance, and publish them all at once.

Docker container image

Docker is a platform used to build, share, and run portable application containers. As of version 3.4, the DITA-OT project provides an official Docker container image that includes everything you need to run the toolkit and publish DITA content from a containerized environment. #3358

New indexing plug-in

DITA-OT 3.4 extracts the PDF indexing code to a separate org.dita.index plug-in, and adds a new depend.org.dita.pdf2.index extension point that can be used to add custom index processing targets to PDF output.

The built-in index processing has been disabled and deprecated. If you have overridden index processing via the transform.topic2fo target in the past, you can set the new org.dita.index.skip property to yes and re-enable the transform.topic2fo.index target with <feature extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/> in your plug-in configuration.

#3390, #3396

Skip HTML5 cover pages

The HTML5 transformation supports a new property that determines whether a table of contents file should be generated to link to the other topics from the input map. The html5.toc.generate parameter is set to yes by default, and creates a cover page named index.html as with previous versions of DITA-OT. If you’re using the nav-toc parameter to embed navigation links in topics, you can set html5.toc.generate to no to stop creating the extra file. #3301

Project files

DITA-OT 3.4 introduces new project files to define publication projects with multiple deliverables. Projects specify a context, output folder, and publication for each deliverable. A re-usable context groups source files and filters, and a publication defines an output format with transformation parameters. You can pass a project file to the dita command to publish multiple deliverables at once.

Project files may be defined in one of three formats: XML, JSON, or YAML. The XML format can be validated with a RELAX NG schema provided in the resources folder of the DITA-OT installation (project.rnc).

#3243, #3256, #3262, #3265, #3268, #3269, #3276, #3298, #3300, #3382, #3388, #3394

Enhancements and changes

In addition to the highlights mentioned above, DITA Open Toolkit Release 3.4 includes the following enhancements and changes to existing features:

  • The original preprocessing and map-first preprocessing pipelines have been simplified to process only the merged root map, where previous versions would redundantly process all DITA maps. #3250
  • Conref processing has been updated to resolve content references to specializations of the referencing element #3264
  • The obsolete build_demo.xml script that was previously used to build Ant samples has been removed from the source code repository. (The file was removed from distribution packages with version 2.1.) #3288
  • Ant scripts have been refactored to simplify <condition> elements with <isset> guards to set properties with plain <property> declarations instead. #3297
  • The logging level for Apache HTTP Client libraries has been reduced to INFO to quiet the default log output. This information can be displayed if necessary by enabling verbose logging. #3307, #3308
  • The ConrefPushParser has been converted from a SAX filter to a DOM filter. #3315
  • Travis CI build stages are now used to run tests and deployments in parallel to speed up continuous integration builds. #3329
  • Several bundled dependencies have been upgraded to the latest versions.
  • XSLT error messages now include location information in more cases to make it easier to find the source of the problem. #3334, #3339, #3341
  • DITA-OT 3.4 no longer includes the TocJS and troff transformation plug-ins in the default distribution. #3363, #3364
    Note: If necessary, legacy plug-ins may be re-installed from earlier DITA-OT distributions, but they are no longer actively maintained or supported by the core toolkit committers. The source code is available on GitHub for anyone interested in maintaining the plug-ins for use with future toolkit versions.
  • The LwDITA plug-in has been updated to version 2.3.2, pulling in a number of fixes for Lightweight DITA processing, including support for absolute links and strikethrough in Markdown input, and updated processing for escaped characters and nested blocks in Markdown output. #3371, #3408
  • The args.logdir parameter (deprecated since DITA-OT 2.5) has been removed. To write the log to a file, use dita --logfile=file or ant -l file and specify the path to the log file. #3398, #3399
  • The source code for the DITA 1.1 and 1.2 plug-ins has been removed from the core repository and extracted to dedicated code repositories. The plug-ins themselves remain available in the DITA-OT 3.4 distribution package. #3401


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

  • Several issues have been resolved in the PDF rendering of a generated index:
    • To work around an open issue with Apache Formatting Objects Processor FOP-2520, DITA-OT 3.4 uses <fo:block> instead of <fo:wrapper> to create the destinations for index links. In previous versions of DITA-OT, index terms that appeared in source files between section titles and paragraph content (and several other places) created empty space in PDF output. #2455, #2914, #3381
    • When publishing to PDF with Antenna House Formatter, destination anchors for index links now use <fo:wrapper> instead of <fo:inline>. In previous versions of DITA-OT, index terms that appeared in source files between section titles and other section content created empty space in PDF output. #3042, #3379
    • Index links are now created correctly when entries have subterms. In previous versions, terms with multiple <index-see-also> subterms failed to generate links for all but the first reference, and dropped all instances of a term if even one instance had a sub-term, an <index-see> or <index-see-also> child. #3314, #3320, #3373
    • References to unavailable <index-see> terms are filtered from the final index. Previous versions would create invalid links if the target terms were not available in the current publication context. #3391
  • Cross-reference links to other topics from short descriptions no longer cause build errors. #3078, #3324
  • In earlier versions, incorrect parameters passed to the dita command could cause the build to fail with a NullPointerException. The Java code has been updated to issue an appropriate error message in these cases, instead of crashing the build. #3360


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

  1. Jarno Elovirta
  2. Robert D Anderson
  3. Roger Sheen
  4. Radu Coravu
  5. Eliot Kimber
  6. Toshihiko Makita

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.4 provides corrections and improvements to existing topics, sample project files in the docsrc/samples/ folder, a Glossary, PDF index, and new information in the following topics:

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

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

  1. Roger Sheen
  2. Lief Erickson
  3. Jarno Elovirta
  4. Robert D Anderson
  5. Eliot Kimber
  6. Ursula Kallio
  7. Jason Fox
  8. Radu Coravu

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