# DITA Open Toolkit 4.4 Release Notes

DITA Open Toolkit 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.

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

## Requirements: Java 17

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

- You can download Oracle distributions from oracle.com/java under commercial license.
- Eclipse Temurin is the free OpenJDK distribution available from adoptium.net.
- Free OpenJDK distributions are also provided by Amazon Corretto, Azul Zulu, and Red Hat.
- Java versions are also available via package managers such as Chocolatey, Homebrew, or SDKMAN!

Note:
The Java virtual machine is generally backwards compatible, so class files built with earlier versions should still run correctly with Java 17 and DITA-OT 4.4. If your DITA-OT installation contains plug-ins with custom Java code, you may need to recompile these with Java 17 — but in most cases, this step should not be necessary.

## DITA-OT 4.4

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.

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.

### 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.