index.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
<reference id="ID" rev="4.4">
  <title>DITA Open Toolkit <keyword keyref="release"/> Release Notes</title>
  <titlealts>
    <navtitle>Release Notes</navtitle>
  </titlealts>

  <abstract>
    <shortdesc>DITA Open Toolkit <keyword keyref="release"/> provides <ph conref="#v4.4/summary"/>.</shortdesc>
    <p conkeyref="conref-task/semver-info"/>
    <note type="tip"><ph conkeyref="conref-task/download-ot"/></note>
  </abstract>

  <reference id="requirements">
    <title>Requirements: Java 17</title>
    <refbody>
      <section>
        <draft-comment author="Roger">Add info on new minimum Java version or any other requirements that have changed
          since previous release.</draft-comment>
        <p conkeyref="reusable-components/java-clients"/>
        <p conkeyref="reusable-components/java-bc"/>
      </section>
    </refbody>
  </reference>

  <reference id="v4.4.1" outputclass="mark">
    <title>DITA-OT <keyword keyref="maintenance-version"/>
      <!--<ph outputclass="small text-muted">released mmmm D, yyyy</ph>-->
    </title>
    <refbody>
      <section>
        <p>DITA Open Toolkit <keyword keyref="maintenance-version"/> is a maintenance release that includes the
          following bug fixes.</p>
        <ul>
          <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.4.1%20sort%3Acreated-asc -->
          <li id="2962">In earlier versions, table entries with a <xmlatt>scope</xmlatt> attribute set to
            <codeph>row</codeph> or <codeph>col</codeph> were not rendered as header cells (<xmlelement
            >th</xmlelement>) in HTML5 output, and the <xmlatt>scope</xmlatt> value itself was not carried through to
            the generated markup. The table templates have been updated to promote these entries to header cells and
            preserve the <xmlatt>scope</xmlatt> value, improving accessibility for complex tables that rely on explicit
            header associations.
            <xref href="https://github.com/dita-ot/dita-ot/issues/2962" format="html" scope="external">#2962</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4776" format="html" scope="external">#4776</xref>
          </li>
          <li id="4777">Several bundled dependencies have been updated to address reported CVEs. Jackson has been
            updated to version 2.21.4 to address <xref
              href="https://nvd.nist.gov/vuln/detail/CVE-2026-54512"
              format="html"
              scope="external"
            >CVE-2026-54512</xref>, and Logback and SLF4J have been updated to versions 1.5.37 and 2.0.18 to address
            <xref
              href="https://nvd.nist.gov/vuln/detail/CVE-2026-13006"
              format="html"
              scope="external"
            >CVE-2026-13006</xref>. DITA-OT is not known to be affected by either vulnerability, but the dependencies
            have been updated proactively so they are no longer flagged by CVE scanners.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4777" format="html" scope="external">#4777</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4778" format="html" scope="external">#4778</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4779" format="html" scope="external">#4779</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4780" format="html" scope="external">#4780</xref>
          </li>
          <li id="4781">The pre-release DITA 2.0 grammar files have been updated to the latest draft published by
            OASIS, which includes fixes and minor updates since the previous update. Anyone building or testing content
            against the DITA 2.0 preview grammar should update to pick up these changes.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4781" format="html" scope="external">#4781</xref>
          </li>
          <li id="4747">In earlier versions, HTML5 templates in the <codeph>related-links:result-group</codeph> mode
            declared a return type of <codeph>element()</codeph>, even though the underlying logic could return no
            results. When a topic had no related links to display, this caused a runtime failure during processing.
            The template signatures in the concept, task, and related-links stylesheets have been corrected to
            <codeph>element()?</codeph> to allow an empty result, so processing no longer fails when there are no
            related links to render.
            <xref href="https://github.com/dita-ot/dita-ot/pull/4747" format="html" scope="external">#4747</xref>
          </li>
        </ul>
        <p>For additional information on the issues resolved since the previous release, see the
          <xref
            href="https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.4.1+is%3Aclosed"
            format="html"
            scope="external"
          >4.4.1 milestone</xref> and
          <xref href="https://github.com/dita-ot/dita-ot/compare/4.4...4.4.1" format="html" scope="external">
            changelog</xref> on GitHub.</p>
      </section>
    </refbody>
  </reference>

  <reference id="v4.4">
    <title>DITA-OT <keyword keyref="release"/>
      <ph outputclass="small text-muted"> released January 31, 2026</ph>
    </title>
    <prolog>
      <metadata>
        <keywords>
          <indexterm/>
        </keywords>
      </metadata>
    </prolog>
    <refbody>
      <section>
        <p>DITA Open Toolkit Release <keyword keyref="release"/> provides 
          <ph id="summary">a new JSON log option and support for additional features in the upcoming DITA 2.0 standard,
            including the <xmlelement>keytext</xmlelement> and <xmlelement>linktitle</xmlelement> elements, new class
            attributes for <xmlelement>navtitle</xmlelement>, and new chunking code</ph>.</p>
      </section>

      <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3ANext%20is%3Aclosed%20label%3Afeature%20sort%3Acreated-asc -->

      <section id="dita-2-0-preview">
        <title><b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates</title>
        <p>In addition to the
          <xref keyref="dita-v2-0-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.</p>
        <ul conkeyref="dita-v2-0-support/added-in-4.4">
          <li/>
        </ul>
        <p conkeyref="dita-v2-0-support/grammar-files"/>
        <note conkeyref="dita-v2-0-support/more-to-come"/>
      </section>

      <section id="4581">
        <title>JSON logging</title>
        <p>A new <parmname>--logger=json</parmname> option enables structured JSON log output for easier log processing
          and analysis.
          <xref href="https://github.com/dita-ot/dita-ot/issues/4581" format="html" scope="external">#4581</xref>
        </p>
        <p>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.</p>
      </section>

      <section id="enhancements">
        <title>Enhancements and changes</title>
        <indexterm/>
        <p>DITA Open Toolkit Release <keyword keyref="release"/> includes the following enhancements and changes to
          existing features:</p>
        <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3ANext+is%3Aclosed+label%3Aenhancement+sort%3Acreated-asc -->
        <ul>
          <li id="4488">In previous releases, DITAVAL <codeph>passthrough</codeph> actions in HTML5 transformations
            supported only simple (ungrouped) profiling attribute values. Passthrough support has been extended to
            profiling attribute groups. When an HTML5 <codeph>data-*</codeph> passthrough attribute is created for a
            value in a group, it is named after the group name. Per the DITA 2.0 specification, the <xmlatt>att</xmlatt>
            value of a <codeph>passthrough</codeph> action can match either a profiling attribute name or a group name,
            and ungrouped values belong to an implicit group named after the attribute.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4488" format="html" scope="external">#4488</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4630" format="html" scope="external">#4630</xref>
          </li>
          <li id="4742">HTML5 output now also supports passthrough for the <xmlatt>importance</xmlatt> attribute,
            allowing this metadata to be passed through to the output HTML for use in downstream processing or styling.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4742" format="html" scope="external">#4742</xref>
          </li>
          <li id="4579">A new <parmname
            >--stacktrace</parmname> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4579" format="html" scope="external">#4579</xref>
          </li>
          <li id="4583">The <parmname>--deliverable</parmname> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4583" format="html" scope="external">#4583</xref>
          </li>
          <li id="4631">In HTML5 transformations, note bodies are rendered as <xmlelement>div</xmlelement> elements with
            <codeph>display: inline</codeph> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4629" format="html" scope="external">#4629</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4631" format="html" scope="external">#4631</xref>
          </li>
          <li id="4637">The keyref parser has been refactored to improve code quality and prepare for future feature
            additions.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4637" format="html" scope="external">#4637</xref>
          </li>
          <li id="4638">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 <codeph>href="topic.dita#id"</codeph>) are not affected.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4638" format="html" scope="external">#4638</xref>
          </li>
          <li>Several bundled dependencies have been upgraded to the latest versions:
            <ul>
              <li>Gradle has been updated to version 9.3.
                <xref href="https://github.com/dita-ot/dita-ot/issues/4727" format="html" scope="external">#4727</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4740" format="html" scope="external">#4740</xref>
              </li>
              <li>JUnit has been updated to version 6.0.2.
                <xref href="https://github.com/dita-ot/dita-ot/issues/4740" format="html" scope="external">#4740</xref>
              </li>
              <li>Logback core has been updated to 1.5.19 to address a security vulnerability.
                <xref href="https://github.com/dita-ot/dita-ot/issues/4743" format="html" scope="external">#4743</xref>
              </li>
              <li>Saxon has been updated to version 12.9, which includes minor bug fixes.
                <xref href="https://github.com/dita-ot/dita-ot/issues/4712" format="html" scope="external">#4712</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4739" format="html" scope="external">#4739</xref>
              </li>
              <li>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.
                <xref href="https://github.com/dita-ot/dita-ot/issues/4665" format="html" scope="external">#4665</xref>
              </li>
            </ul>
          </li>
          <li>Various internal code improvements have been made for better code quality, test coverage, and
            maintainability:
            <ul>
              <li>Test class names now consistently use a <codeph>Test</codeph> suffix
                <xref href="https://github.com/dita-ot/dita-ot/issues/4657" format="html" scope="external">#4657</xref>
              </li>
              <li>File stream creation now uses the modern <codeph>Files</codeph> API
                <xref href="https://github.com/dita-ot/dita-ot/issues/4663" format="html" scope="external">#4663</xref>
              </li>
              <li>Unit tests have been added for coderef processing
                <xref href="https://github.com/dita-ot/dita-ot/issues/4664" format="html" scope="external">#4664</xref>
              </li>
              <li>Gradle build scripts have been refactored
                <xref href="https://github.com/dita-ot/dita-ot/issues/4666" format="html" scope="external">#4666</xref>
              </li>
              <li>Debug output now includes task descriptions for XHTML builds
                <xref href="https://github.com/dita-ot/dita-ot/issues/4672" format="html" scope="external">#4672</xref>
              </li>
              <li>Integration test result reporting has been improved
                <xref href="https://github.com/dita-ot/dita-ot/issues/4673" format="html" scope="external">#4673</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4676" format="html" scope="external">#4676</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4677" format="html" scope="external">#4677</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4678" format="html" scope="external">#4678</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4679" format="html" scope="external">#4679</xref>
              </li>
              <li>Preprocessing modules have been refactored for better readability
                <xref href="https://github.com/dita-ot/dita-ot/issues/4680" format="html" scope="external">#4680</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4684" format="html" scope="external">#4684</xref>
              </li>
              <li>Test method naming conventions have been standardized
                <xref href="https://github.com/dita-ot/dita-ot/issues/4690" format="html" scope="external">#4690</xref>
              </li>
              <li>General code refactoring for improved quality and performance
                <xref href="https://github.com/dita-ot/dita-ot/issues/4718" format="html" scope="external">#4718</xref>,
                <xref href="https://github.com/dita-ot/dita-ot/issues/4724" format="html" scope="external">#4724</xref>
              </li>
              <li id="4685">
                <p>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.
                  <xref
                    href="https://github.com/dita-ot/dita-ot/issues/4685"
                    format="html"
                    scope="external"
                  >#4685</xref>,
                  <xref
                    href="https://github.com/dita-ot/dita-ot/issues/4716"
                    format="html"
                    scope="external"
                  >#4716</xref></p>
                <p id="4716">These internal infrastructure improvements provide a foundation for more sophisticated link
                  and dependency tracking between files and topics. The new <codeph>Graph</codeph> and
                    <codeph>UriGraph</codeph> classes enable DITA-OT to model and traverse relationships between
                  resources, which will support future enhancements to content processing and validation.</p>
              </li>
            </ul>
          </li>
        </ul>
      </section>

      <section id="bugs">
        <title>Bug fixes</title>
        <indexterm/>
        <p>DITA Open Toolkit Release <keyword keyref="release"/> provides fixes for the following bugs:</p>
        <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3ANext+is%3Aclosed+label%3Abug+sort%3Acreated-asc -->
        <ul>
          <li id="4036">Earlier versions of DITA-OT threw a <codeph>NullPointerException</codeph> when using the
            <parmname>--root-chunk-override</parmname> option with the DITA 2.0 <codeph>combine</codeph> value. Chunk
            processing has been updated to handle this case correctly.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4036" format="html" scope="external">#4036</xref>
          </li>
          <li id="4464">In previous releases, DITAVAL <codeph>passthrough</codeph> actions in HTML5 transformations were
            not applied to top-level (root) <xmlelement>topic</xmlelement> elements, even though they worked correctly
            for nested topics. The root-topic template has been updated to generate the expected
            <codeph>data-<varname>attname</varname></codeph> passthrough attributes on the HTML5 <xmlelement
            >body</xmlelement> element.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4464" format="html" scope="external">#4464</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4639" format="html" scope="external">#4639</xref>
          </li>
          <li id="4511">Using the <parmname>--root-chunk-override=combine</parmname> option with DITA 2.0 content that
            contained <xmlelement>xref</xmlelement> elements caused a <codeph>NullPointerException</codeph> during link
            rewriting. Chunk processing has been updated to handle cross-references correctly.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4511" format="html" scope="external">#4511</xref>
          </li>
          <li id="4513">Using the <parmname>--root-chunk-override=combine</parmname> option with DITA 2.0 content that
            contained tables caused a <codeph>SAXParseException</codeph> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4513" format="html" scope="external">#4513</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4738" format="html" scope="external">#4738</xref>
          </li>
          <li id="4688">The Gradle build configuration has been updated to correctly locate the Node.js executable path
            on Windows systems.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4688" format="html" scope="external">#4688</xref>
          </li>
          <li id="4695">When using a DITA 2.0 map schema, the <xmlelement>navtitle</xmlelement> element within
            <xmlelement>topicref</xmlelement> 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
            <xmlelement>navtitle</xmlelement>.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4695" format="html" scope="external">#4695</xref>
          </li>
          <li id="4698">Combine chunking for the root map in DITA 2.0 has been fixed.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4698" format="html" scope="external">#4698</xref>
          </li>
          <li id="4701">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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4705" format="html" scope="external">#4705</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4706" format="html" scope="external">#4706</xref>
          </li>
          <li id="4686">In XHTML and Eclipse Help output, trademark symbols in related links caused processing to fail
            because the <codeph>key()</codeph> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4686" format="html" scope="external">#4686</xref>,
            <xref href="https://github.com/dita-ot/dita-ot/issues/4717" format="html" scope="external">#4717</xref>
          </li>
          <li id="4731">From the initial public release of DITA-OT, section titles in HTML output have been styled with
            a CSS <codeph>color</codeph> 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.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4731" format="html" scope="external">#4731</xref>
          </li>
          <li id="4732">The PDF2 parameter <parmname>outputFile.base</parmname> has been marked as deprecated. (Use
              <parmname>args.output.base</parmname> instead.)
            <xref href="https://github.com/dita-ot/dita-ot/issues/4732" format="html" scope="external">#4732</xref>,
            <xref
              href="https://github.com/dita-ot/docs/issues/648"
              format="html"
              scope="external"
            >dita-ot/docs#648</xref>
          </li>
          <li id="4733">A stale reference to the deprecated <parmname>args.logdir</parmname> parameter has been removed
            from test code. This parameter was deprecated in DITA-OT 2.5 and removed in 3.4.
            <xref href="https://github.com/dita-ot/dita-ot/issues/4733" format="html" scope="external">#4733</xref>
          </li>
        </ul>
      </section>

      <section id="contrib">
        <title>Contributors</title>
        <p>DITA Open Toolkit Release <keyword keyref="release"/> includes
          <xref keyref="contributions"/> by the following people:</p>
        <!--  https://github.com/tj/git-extras/blob/master/Commands.md#git-summary – `git summary 4.3..` -->
        <draft-comment author="Roger">NOTE: This lists contributions to the core toolkit, not docs.</draft-comment>
        <ol>
          <li>Jarno Elovirta</li>
          <li>Dávid Bertalan</li>
          <li>Roger Sheen</li>
          <li>Robert D. Anderson</li>
          <li>Chris Papademetrious</li>
          <li>Joshua Johnson</li>
          <li>Julien Lacour</li>
          <li>Guillaume Delory</li>
          <li>Gregor Latuske</li>
        </ol>
        <p>For the complete list of changes since the previous release, see the
          <xref
            href="https://github.com/dita-ot/dita-ot/compare/4.3...4.4"
            format="html"
            scope="external"
          >changelog</xref> on GitHub.</p>
      </section>

      <section id="docs">
        <title>Documentation updates</title>
        
        <p>The documentation for DITA Open Toolkit Release <keyword keyref="release"/> provides corrections and
          improvements to existing topics, along with new information in the following topics:</p>
        <ul>
          <li>
            <xref keyref="dita-command-arguments"/></li>
          <li>
            <xref keyref="dita-v2-0-support"/></li>
          <li>
            <xref keyref="dita-ot-day-videos-intro-2025">DITA-OT Day 2025 videos</xref></li>
          <li>
            <xref keyref="logging"/></li>
          <li>
            <xref keyref="migrating-to-4.4"/></li>
          <li>
            <xref keyref="using-docker-images"/></li>
        </ul>
        
        <p>For additional information on documentation issues resolved in DITA Open Toolkit Release <keyword
            keyref="release"
          />, see the
          <xref
            href="https://github.com/dita-ot/docs/issues?q=milestone%3A4.4+is%3Aclosed"
            format="html"
            scope="external"
          ><keyword keyref="release"/> milestone</xref> in the documentation repository.</p>
        <p>DITA Open Toolkit Release <keyword keyref="release"/> includes
          <xref keyref="docs-contributions"/> by the following people:</p>
        <draft-comment author="Roger">NOTE: This lists contributions to docs, not to the core toolkit.</draft-comment>
        <ol>
          <li>Roger Sheen</li>
          <li>Jarno Elovirta</li>
          <li>Darrenn Jackson</li>
          <li>Dávid Bertalan</li>
          <li>Jeremy Jeanne</li>
          <li>Lief Erickson</li>
          <li>Stefan Jung</li>
        </ol>
        <p>For the complete list of documentation changes since the previous release, see the
          <xref
            href="https://github.com/dita-ot/docs/compare/4.3...4.4"
            format="html"
            scope="external"
          >changelog</xref>.</p>
      </section>
    </refbody>
  </reference>
</reference>