DITA Open Toolkit 4.4 Release Notes

DITA Open Toolkit Release 4.4 provides a new JSON log option and support for additional features in the upcoming DITA 2.0 standard, including the <keytext> and <linktitle> elements, new class attributes for <navtitle>, and new chunking code.

Preview DITA 2.0 updates

In addition to the DITA 2.0 preview support provided in DITA-OT 3.5 – 4.3, this release includes updated processing for the latest draft versions of the DITA 2.0 grammar files from OASIS.

• DITA-OT now supports the DITA 2.0 <keytext> element and implements the updated DITA 2.0 rules for generating key variable text. #4644

  In DITA 2.0, the <keytext> element provides a more flexible way to define the text content for key references. When a key is defined with <keytext>, this content is used to populate key references that resolve to text.

  Key processing now determines the DITA version of the map that declared each key and applies the appropriate resolution rules. When you combine DITA 1.x and DITA 2.0 maps in a single publication:

  • Key references to keys defined in DITA 1.x maps use the <keyword> element for text resolution (as in previous versions).
  • Key references to keys defined in DITA 2.0 maps use the <keytext> element for text resolution (following the DITA 2.0 specification).

  This approach allows you to gradually migrate content to DITA 2.0 without rewriting existing key definitions. However, mixing DITA versions in a single publication is not generally recommended.

• Simple chunking cases in DITA 1.x maps can now be processed using the DITA 2.0 chunking module in compatibility mode. For example, a DITA 1.3 map with chunk="to-content" is now processed as if it used the DITA 2.0 chunk="combine" action. This refactoring improves reliability by leveraging the newer chunking code, which has fewer bugs than the legacy implementation. Note that this may change how splitting operations generate file names. #4600

• The DITAVAL @outputclass attribute has been renamed to @add-outputclass to match the DITA 2.0 specification. Support for the old attribute name is retained for backwards compatibility, but a DOTA014W warning message is now generated when the deprecated @outputclass attribute is used. #4635

• DITA 2.0 chunk processing has been improved to support multiple operation tokens. This refactoring work lays the groundwork for future support of select tokens in DITA 2.0 chunk processing. #4711

• DITA-OT now supports the DITA 2.0 <linktitle> element and recognizes both the DITA 1.3 and DITA 2.0 class attributes for <navtitle>. When using a DITA 2.0 root map, the preprocessed map will contain both <linktext> (for DITA 1.3 compatibility) and <linktitle> (for DITA 2.0) elements. Plug-ins that handle <navtitle> or <linktext> may need to be updated to handle these new elements. #4734

• DITA 2.0 grammar files have been updated to the latest draft versions from OASIS (as of January 25, 2026). This update removes the <state> and <unknown> elements from the base grammar, changes the new @outputclass attribute in DITAVAL to @add-outputclass, and modifies how default values are set for @title-role in the Alternative Titles RNG module, for improved editing experience. #4744

  In the technical content grammar, several elements have been removed from the Glossary Entry module:

  • <glossAbbreviation>
  • <glossAlternateFor>
  • <glossPartOfSpeech>
  • <glossProperty>
  • <glossScopeNote>
  • <glossShortForm>
  • <glossStatus>

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.

JSON logging

A new --logger=json option enables structured JSON log output for easier log processing and analysis. #4581

When logging to standard output, each line is a separate JSON object. When logging to a file, the output is formatted as a JSON array. This structured format simplifies integration with log aggregation tools and automated build pipelines that need to parse DITA-OT output programmatically.

Enhancements and changes

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

• In previous releases, DITAVAL passthrough actions in HTML5 transformations supported only simple (ungrouped) profiling attribute values. Passthrough support has been extended to profiling attribute groups. When an HTML5 data-* passthrough attribute is created for a value in a group, it is named after the group name. Per the DITA 2.0 specification, the @att value of a passthrough action can match either a profiling attribute name or a group name, and ungrouped values belong to an implicit group named after the attribute. #4488, #4630
• HTML5 output now also supports passthrough for the @importance attribute, allowing this metadata to be passed through to the output HTML for use in downstream processing or styling. #4742
• A new --stacktrace command-line option has been added to print the full Java stack trace when an error occurs. This option is useful for debugging and troubleshooting, and can help developers and support teams diagnose issues more quickly. By default, stack traces are no longer included in verbose logging output to reduce noise for end users. #4579
• The --deliverable option can now be specified multiple times on the command line to publish several deliverables from a project file in a single build. This allows you to select specific deliverables without publishing all deliverables defined in the project. #4583
• In HTML5 transformations, note bodies are rendered as <div> elements with display: inline applied to allow single-line note rendering for inline note content. A CSS comment has been added to the default stylesheets to explain this styling choice. #4629, #4631
• The keyref parser has been refactored to improve code quality and prepare for future feature additions. #4637
• Topic ID values are now cached during keyref resolution as a performance optimization. This cache is used for key definitions that point to a file without a topic ID in the fragment identifier. Key definitions that include a topic ID (such as href="topic.dita#id") are not affected. #4638
• Several bundled dependencies have been upgraded to the latest versions:
  • Gradle has been updated to version 9.3. #4727, #4740
  • JUnit has been updated to version 6.0.2. #4740
  • Logback core has been updated to 1.5.19 to address a security vulnerability. #4743
  • Saxon has been updated to version 12.9, which includes minor bug fixes. #4712, #4739
  • XSpec has been upgraded to version 3.2.2, which improves XSLT test capabilities and now reports all failing tests in a file instead of just the first one. #4665
• Various internal code improvements have been made for better code quality, test coverage, and maintainability:
  • Test class names now consistently use a Test suffix #4657
  • File stream creation now uses the modern Files API #4663
  • Unit tests have been added for coderef processing #4664
  • Gradle build scripts have been refactored #4666
  • Debug output now includes task descriptions for XHTML builds #4672
  • Integration test result reporting has been improved #4673, #4676, #4677, #4678, #4679
  • Preprocessing modules have been refactored for better readability #4680, #4684
  • Test method naming conventions have been standardized #4690
  • General code refactoring for improved quality and performance #4718, #4724

  • A new directed graph data structure has been added to track dependencies between resources identified by URI. A generic rose tree data structure has also been added to replace earlier ad hoc implementations. #4685, #4716

    These internal infrastructure improvements provide a foundation for more sophisticated link and dependency tracking between files and topics. The new Graph and UriGraph classes enable DITA-OT to model and traverse relationships between resources, which will support future enhancements to content processing and validation.

Bug fixes

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

• Earlier versions of DITA-OT threw a NullPointerException when using the --root-chunk-override option with the DITA 2.0 combine value. Chunk processing has been updated to handle this case correctly. #4036
• In previous releases, DITAVAL passthrough actions in HTML5 transformations were not applied to top-level (root) <topic> elements, even though they worked correctly for nested topics. The root-topic template has been updated to generate the expected data-attname passthrough attributes on the HTML5 <body> element. #4464, #4639
• Using the --root-chunk-override=combine option with DITA 2.0 content that contained <xref> elements caused a NullPointerException during link rewriting. Chunk processing has been updated to handle cross-references correctly. #4511
• Using the --root-chunk-override=combine option with DITA 2.0 content that contained tables caused a SAXParseException due to unbound namespace prefixes. The namespace prefix tracking has been fixed to ensure that internal attributes are correctly handled when links are inserted during chunk processing. #4513, #4738
• The Gradle build configuration has been updated to correctly locate the Node.js executable path on Windows systems. #4688
• When using a DITA 2.0 map schema, the <navtitle> element within <topicref> was ignored, causing navigation entries to be suppressed or flattened in HTML5 output. The transformation now matches both the DITA 1.3 and DITA 2.0 class values for <navtitle>. #4695
• Combine chunking for the root map in DITA 2.0 has been fixed. #4698
• The attribute stack in the force-unique filter and merge-map parser modules was not being correctly maintained, which could cause attributes to be incorrectly applied during processing. The stack management has been fixed to ensure attributes are properly tracked. #4705, #4706
• In XHTML and Eclipse Help output, trademark symbols in related links caused processing to fail because the key() function was called on an intermediate tree without a document node. This fix ports an earlier HTML5 correction to the XHTML transformation, passing the original root node as a tunnel parameter for key lookups. #4686, #4717
• From the initial public release of DITA-OT, section titles in HTML output have been styled with a CSS color property that set text color to black. This creates problems in inverted color schemes like dark mode themes, where section titles did not have sufficient contrast with the background. No other heading levels specify text color, so this version removes the color property to allow themes to modify section title color along with other headings and text. #4731
• The PDF2 parameter outputFile.base has been marked as deprecated. (Use args.output.base instead.) #4732, dita-ot/docs#648
• A stale reference to the deprecated args.logdir parameter has been removed from test code. This parameter was deprecated in DITA-OT 2.5 and removed in 3.4. #4733

Contributors

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

1. Jarno Elovirta
2. Dávid Bertalan
3. Roger Sheen
4. Robert D. Anderson
5. Chris Papademetrious
6. Joshua Johnson
7. Julien Lacour
8. Guillaume Delory
9. Gregor Latuske

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

Documentation updates

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

• Arguments and options for the dita command
• DITA 2.0 preview support
• DITA-OT Day 2025 videos
• Logging build information
• Migrating to release 4.4
• Running the dita command from a Docker image

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

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

1. Roger Sheen
2. Jarno Elovirta
3. Darrenn Jackson
4. Dávid Bertalan
5. Jeremy Jeanne
6. Lief Erickson
7. Stefan Jung

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