From c66e1a9503bd3ad28f1ad5fb8eb200bd1ab89598 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 19 Jan 2026 21:44:05 +0100 Subject: [PATCH 01/36] Bump keys & Docker image version to 4.4 Signed-off-by: Roger Sheen --- resources/key-definitions.ditamap | 4 ++-- samples/docker/Dockerfile | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index d2cd3e91..f7b3a5fe 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -16,7 +16,7 @@ - 4.3 + 4.4 @@ -26,7 +26,7 @@ - 4.3.5 + 4.4 diff --git a/samples/docker/Dockerfile b/samples/docker/Dockerfile index b4452b3e..b309f760 100644 --- a/samples/docker/Dockerfile +++ b/samples/docker/Dockerfile @@ -1,5 +1,5 @@ # Use the latest DITA-OT image ↓ as parent: -FROM ghcr.io/dita-ot/dita-ot:4.3.5 +FROM ghcr.io/dita-ot/dita-ot:4.4 # Install a custom plug-in from a remote location: RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip From eee545e76422e79893047b1aa15f7f2c3f0d8716 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 19 Jan 2026 21:46:33 +0100 Subject: [PATCH 02/36] Archive 4.3 Release Notes for posterity Signed-off-by: Roger Sheen --- release-notes/rel4.3.dita | 550 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 release-notes/rel4.3.dita diff --git a/release-notes/rel4.3.dita b/release-notes/rel4.3.dita new file mode 100644 index 00000000..9750592d --- /dev/null +++ b/release-notes/rel4.3.dita @@ -0,0 +1,550 @@ + + + + + DITA Open Toolkit <keyword keyref="release"/> Release Notes + + Release Notes + + + + DITA Open Toolkit is a maintenance release that fixes issues + reported in DITA-OT , which includes . +

+ + + + + Requirements: Java 17 + +

+ Add info on new minimum Java version or any other requirements that have changed + since previous release. +

+

+

+ + + + + DITA-OT <keyword keyref="maintenance-version"/> + <ph outputclass="small text-muted">released October 21, 2025</ph> + + +
+

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

+
    + +
  • In DITA-OT 4.3.3, filtered, flagged, or duplicated topics were not copied to the temporary + directory, which caused builds to fail. The merge map parser and force unique filter modules have been + updated to ensure that attributes are correctly applied, so the topics are processed as intended. + #4701, + #4704, + #4708 +
    • +
+

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

+
+ + + + + DITA-OT 4.3.4 + <ph outputclass="small text-muted">released July 30, 2025</ph> + + +
+

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

+
    + +
  • In earlier versions, links to content outside the map directory were not generated correctly in + HTML5 output when the nav-toc parameter was set to or + and the generate.copy.outer parameter was set to + to shift the output directory. Processing now follows topics and common stylesheets to + their new locations and writes links with correct paths even if the folders move. + #4478, + #4641, + #4667, + #4675 +
    • +
  • Additional tests have been added to verify the correct behavior of the + nav-toc parameter, and existing tests have been consolidated and parameterized for + easier maintenance. + #4660 +
    • +
  • Unit tests have been updated to resolve Windows-specific issues with line endings, file path + separators, and temporary file mappings. + #4662 +
    • +
+

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

+
+ + + + + DITA-OT 4.3.3 + <ph outputclass="small text-muted">released June 22, 2025</ph> + + +
+

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

+
    + +
  • Earlier versions of DITA-OT did not always cascade map-level attributes such as + format or scope correctly. Processing has been updated to ensure that + map metadata cascades as mandated by §2.2.4.4 of the + . + #4645 +
    • +
+

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

+
+ + + + + DITA-OT 4.3.2 + <ph outputclass="small text-muted">released June 5, 2025</ph> + + +
+

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

+
    + +
  • The GitHub release workflow was updated in DITA-OT 4.3.1 to build Docker images for both + linux/amd64 and linux/arm64 architectures, but this caused errors in + GitHub Actions as reported in + dita-ot-action#11. The release workflow has been updated to use the official Docker actions, which + support multi-platform builds and push the resulting platform-specific images to Docker Hub. + #4609 +
    • +
  • Table processing has been updated to improve handling for broken tables. If the + morerows attribute value is not an integer, strict processing mode will now report an + exception. If a row has fewer columns than the preceding row, processing will continue instead of failing + with a Java exception. + #4620, + #4628 +
    • +
  • Earlier versions of the map-first pre-processing routines in preprocess2 did + not apply stylesheets and parameters that were passed to the mapref processing phase by + custom plug-ins. The mapref module configuration has been updated to ensure that + preprocess2 respects the same parameters as the original pre-processing routine. + #4624, + #4625 +
    • +
  • Several dependencies have been upgraded to include the latest utility versions and fix security issues in + bundled libraries. + #4632 +
      +
    • Apache Commons IO 2.19.0
      • +
    • ICU4J 77.1
      • +
    • Guava 33.4.8-jre
      • +
    • Jackson data binding library 2.19.0
      • +
    • Jing 20241231
      • +
    • Logback Classic Module 1.5.18
      • +
    • Saxon 12.7
      • +
    • SLF4J 2.0.17
      • +
    • XML Resolver 5.3.3
      • +
    +
    • +
  • The bundled version has been updated to 2.11, which includes + PDFBox 3 and the latest versions of the and libraries. + #4623, + #4634 +

    (For details on recent changes, see the + .)

    +
    • +
+

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

+
+ + + + + DITA-OT 4.3.1 + <ph outputclass="small text-muted">released March 23, 2025</ph> + + +
+

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

+
    + +
  • DITA-OT 4.2 and later versions produced broken links in the navigation ToC when the + copy-to attribute was defined on topic references, or the + force-unique option was used. Generated temporary file names were used instead of + the copy-to attribute value. The copy-to attribute value is now respected + to ensure the correct links are written to the ToC. + #4564, + #4569 +
    • +
  • DITA-OT 4.3 included a regression bug that generated output in the out + subdirectory of the DITA-OT installation directory if the output location was not explicitly specified. In + this case, output is now generated in the out subdirectory of the current directory as + in DITA-OT 4.2.4 and earlier versions. + #4589, + #4594 +
    • +
  • The new validate subcommand introduced in DITA-OT 4.3 can now also be run by + setting the -f or --format options to validate. + The dita command line interface has also been updated to prevent conflicts between the + validate subcommand and the existing validate parameter. + #4590, + #4592, + #4602, + #4603 +
    • +
  • DITA-OT Docker images can now be built for both 64-bit Linux AMD and ARM architectures. No + changes are required to benefit from this enhancement. Docker should automatically select the image that + corresponds to the current machine architecture. + #4593 +
    • +
  • Earlier versions of DITA-OT generated invalid nested paragraphs in HTML output when the + lines element was used in a paragraph. Processing has been updated to ensure that + lines content is treated as a block element and rendered in separate paragraphs. + #4596, + #4599 +
    • +
  • Earlier versions of DITA-OT miscalculated the base directory when publications included + resource-only topics that were outside of the root map directory. Resource-only topics are now ignored in + this process to ensure that relative paths between resources are generated correctly. + #4606 +
    • +
  • Several dependencies have been upgraded to include the latest utility versions and fix security issues: +
      +
    • Ant 1.10.15 + #4595 +
      • +
    • Logback 1.5.17 + #4588 +
      • +
    • Saxon 12.5 + #4595 +
      • +
    +
    • +
+

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

+
+ + + + + DITA-OT <keyword keyref="release"/> + <ph outputclass="small text-muted"> released February 15, 2025</ph> + + + + + + + + + +
+

DITA Open Toolkit Release includes + new init and validate subcommands that can be used to + set up projects from a template and check files for errors before publishing. You can now publish multiple + formats on the command line at once, add raw DITA to Markdown files, and publish bookmaps with PDF + themes.

+
+ + + +
+ <b outputclass="badge badge-primary">Preview</b> Init subcommand +

The new init subcommand initializes a project with files from a template. + #4509, + #4523 +

+

The initial implementation is a preview feature designed to illustrate how project templates work. You can + use templates as a starting point for new publications with required metadata, media assets, or custom + stylesheets, or provide examples of your organization’s preferred markup.

+
    +
  • For a list of available templates, run + init + --list
    • +
  • To add files from a template to the current directory, run + init + template
    • +
+

+ Sample project templates are provided in the + new + org.dita.init plug-in. If you have a common project structure that would be useful + beyond your organization, you can contribute new templates to future DITA-OT versions, or create a custom + plug-in with company-specific project templates. +
+ +
+ Validate subcommand +

A new validate subcommand can be used to check input files for errors before + publishing. + #4397, + #4400 +

+

This command runs the pre-processing routines in strict mode and reports any errors or warnings. This is + ideal for continuous integration scenarios, as it allows you to quickly check contributions for errors without + building output.

+

A new depend.validate extension point defines an Ant target to run with the + dita validate subcommand after pre-processing, so you can extend the default validation + mechanisms with your own checks.

+
+ +
+ Multiple output formats from CLI +

You can now publish multiple formats at once from a single dita command + sequence. + #4486

+

To produce several output formats from a single build, pass the --format option for each + transformation, or use the -f shorthand. For example: + -i sample.ditamap -f html5 -f pdf + The result will be the same as if you had issued separate commands for each format: + --input=sample.ditamap --format=html5 + --input=sample.ditamap --format=pdf +

+

This can be used as a simple alternative to a DITA-OT + project file that defines multiple deliverables.

+
+ +
+ Lightweight DITA and Markdown updates +

The org.lwdita plug-in has been updated to version , + which includes a series of bug fixes and support for additional DITA constructs in Markdown input, + including:

+
    +
  • Language identifiers in fenced code blocks can now be processed with an optional prefix to enable syntax + highlighting in environments that require different keywords. For example, if Markdown files contain code + blocks with JavaScript code, they may start with ```js to display the code block with + syntax highlighting on GitHub. The plug-in can now add a prefix like language- to the DITA + outputclass value, included in HTML5 as class="language-js" for + with libraries like + . + #228 +
    • +
  • Admonition types are no longer case-sensitive, so both !!! note and !!! + Note will be rendered as DITA note elements, regardless of the + capitalization of the type keyword. + #229 +
    • +
  • If you need to include DITA content that has no equivalent markup in + , you can now use raw DITA XML directly in Markdown files. You can use + this approach to include things like xmlelement or + hazardstatement, which would otherwise be impossible to express in Markdown. + #217 +
    • +
  • Earlier versions would crash when processing Markdown files that did not begin with a heading. These files + are now converted to valid DITA with an empty title element, and an error message + appears in the log to aid in debugging. + #223 +
    • +
+
+ +
+ +
+ <b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates +

In addition to the + provided in DITA-OT 3.5 – 4.2, this release includes updated processing for + the latest draft versions of the DITA 2.0 grammar files from OASIS (as of ). +

+
    +
  • +
+

+ +

+ +
+ Enhancements and changes + +

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

+ +
    +
  • To reduce page load times, HTML5 output now uses + lazy loading for external images. + #4001, + #4005 + Local and peer image resources are loaded eagerly as in previous versions, but images defined with + scope="external" are now output with the loading + attribute set to "lazy" by default. A new set-image-loading template mode + allows custom plug-ins to override the default behavior if necessary.
    • +
  • The Java code for the map-first pre-processing routines now includes Javadoc comments to + document how the various stages are implemented. This documentation is not published separately, but is + available to developers who need to extend map processing or topic processing in custom plug-ins. Many + development environments extract and display the Javadoc information while viewing the source code. + #4404 +
    • +
  • The Java code has been modernized to use more standard library features and reduce dependencies + on external libraries, and restructured with automatic refactoring tools to make it easier to read and + maintain. + #4407, + #4441, + #4442, + #4444, + #4498 +
    • +
  • A new DOTJ088E error message makes it easier to identify XML parsing + exceptions in the log. + #4408 + The error appears when the input is in some way invalid but can still be parsed. The message content begins + with “XML parsing error:” and provides additional context from the parser in the + reason. As with other error messages, custom plug-ins may override the message + content or severity.
    • +
  • DITA-OT uses the Xerces SecurityManager to protect against the so-called + “billion + laughs attack”, an entity expansion technique that can cause XML parsers to run out of memory and + overload the CPU when parsing maliciously crafted files. DITA-OT will now stop parsing and report an error + when processing any files that exceed the entity limit imposed by the security manager library. + #4542, + #4556 +
    • +
  • Several bundled dependencies have been upgraded to the latest versions: +
      +
    • 2.10 (including the and + libraries) + #4519, + #4565 +
      • +
    +
    • +
+
+ +
+ Bug fixes + +

DITA Open Toolkit Release provides fixes for the following bugs:

+ +
    +
  • In earlier versions, installing a plug-in from a path that contained the at-sign character + “@” failed with an InvalidArgumentException. The implementation has been + updated to ensure these paths are handled correctly. + #4354, + #4558 +
    • +
  • Earlier versions issued the DOTJ037W twice when running transformations with + the validate parameter set to false. This warning has been moved from + the Java code to Ant, which ensures that it only appears once for each transformation. + #4377, + #4396 +
    • +
+
+ +
+ Contributors +

DITA Open Toolkit Release includes + by the following people:

+ + NOTE: This lists contributions to the core toolkit, not docs. +
    +
  1. Jarno Elovirta
    2. +
  2. Julien Lacour
    3. +
  3. Robert D Anderson
    4. +
  4. Roger Sheen
    5. +
  5. Andrei Pomacu
    6. +
  6. Chris Papademetrious
    7. +
  7. Jason Fox
    8. + +
+

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

+
+ +
+ Documentation updates +

The documentation for DITA Open Toolkit Release has been reorganized to simplify + the navigation in HTML versions and reduce the number of parts in PDF output. All of the content from previous + versions is still available, though arranged slightly differently. The diagram in + shows the previous structure on the left, and the new locations on the + right.

+ + DITA-OT <keyword keyref="release"/> navigation changes + + +

+

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

+

DITA Open Toolkit Release includes + by the following people:

+ NOTE: This lists contributions to docs, not to the core toolkit. +
    +
  1. Roger Sheen
    2. +
  2. Jarno Elovirta
    3. +
  3. Lief Erickson
    4. +
  4. Stefan Weil
    5. +
+

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

+
+ + + From 13ff8830cbad4a9fd36eaf9e841ea69553bb43ea Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 19 Jan 2026 22:00:11 +0100 Subject: [PATCH 03/36] Replace keys in 4.3 Release Notes archive Signed-off-by: Roger Sheen --- release-notes/rel4.3.dita | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/release-notes/rel4.3.dita b/release-notes/rel4.3.dita index 9750592d..9a64f866 100644 --- a/release-notes/rel4.3.dita +++ b/release-notes/rel4.3.dita @@ -2,14 +2,14 @@ - DITA Open Toolkit <keyword keyref="release"/> Release Notes + DITA Open Toolkit 4.3 Release Notes Release Notes - DITA Open Toolkit is a maintenance release that fixes issues - reported in DITA-OT , which includes . + DITA Open Toolkit 4.3.5 is a maintenance release that fixes issues + reported in DITA-OT 4.3, which includes .

@@ -27,12 +27,12 @@ - DITA-OT <keyword keyref="maintenance-version"/> + <title>DITA-OT 4.3.5 <ph outputclass="small text-muted">released October 21, 2025</ph>

-

DITA Open Toolkit is a maintenance release that includes the +

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

    @@ -272,7 +272,7 @@ - DITA-OT <keyword keyref="release"/> + <title>DITA-OT 4.3 <ph outputclass="small text-muted"> released February 15, 2025</ph> @@ -284,7 +284,7 @@
    -

    DITA Open Toolkit Release includes +

    DITA Open Toolkit Release 4.3 includes new init and validate subcommands that can be used to set up projects from a template and check files for errors before publishing. You can now publish multiple formats on the command line at once, add raw DITA to Markdown files, and publish bookmaps with PDF @@ -406,7 +406,7 @@

    Enhancements and changes -

    DITA Open Toolkit Release includes the following enhancements and changes to +

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

      @@ -467,7 +467,7 @@
      Bug fixes -

      DITA Open Toolkit Release provides fixes for the following bugs:

      +

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

      • In earlier versions, installing a plug-in from a path that contained the at-sign character @@ -487,7 +487,7 @@
        Contributors -

        DITA Open Toolkit Release includes +

        DITA Open Toolkit Release 4.3 includes by the following people:

        NOTE: This lists contributions to the core toolkit, not docs. @@ -511,13 +511,13 @@
        Documentation updates -

        The documentation for DITA Open Toolkit Release has been reorganized to simplify +

        The documentation for DITA Open Toolkit Release 4.3 has been reorganized to simplify the navigation in HTML versions and reduce the number of parts in PDF output. All of the content from previous versions is still available, though arranged slightly differently. The diagram in shows the previous structure on the left, and the new locations on the right.

        - DITA-OT <keyword keyref="release"/> navigation changes + DITA-OT 4.3 navigation changes

        @@ -528,8 +528,8 @@ href="https://github.com/dita-ot/docs/issues?q=milestone%3A4.3+is%3Aclosed" format="html" scope="external" - > milestone in the documentation repository.

        -

        DITA Open Toolkit Release includes + >4.3 milestone in the documentation repository.

        +

        DITA Open Toolkit Release 4.3 includes by the following people:

        NOTE: This lists contributions to docs, not to the core toolkit.
          From 656a2c1ddfbfb9f20c7a9c6dcde4bd0a12882d9f Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 19 Jan 2026 22:03:47 +0100 Subject: [PATCH 04/36] Add 4.4 Release Notes key Signed-off-by: Roger Sheen --- resources/external-links.ditamap | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/resources/external-links.ditamap b/resources/external-links.ditamap index 1a2e3d82..35a627eb 100644 --- a/resources/external-links.ditamap +++ b/resources/external-links.ditamap @@ -315,6 +315,16 @@ DITA-OT 4.3 Release Notes + + + DITA-OT 4.4 Release Notes + + From b1fcb0301d8eedd58a2bb14c04a49dc56c8ceaeb Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 19 Jan 2026 22:07:37 +0100 Subject: [PATCH 05/36] Add 4.4 Release Notes to release history Signed-off-by: Roger Sheen --- resources/reltable.ditamap | 1 + 1 file changed, 1 insertion(+) diff --git a/resources/reltable.ditamap b/resources/reltable.ditamap index a58e518c..eb61d868 100644 --- a/resources/reltable.ditamap +++ b/resources/reltable.ditamap @@ -363,6 +363,7 @@ + From 90a8c987fd0d86092d069a4454c893930adb4f44 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Tue, 20 Jan 2026 00:00:09 +0100 Subject: [PATCH 06/36] Prepare 4.4 Release Notes stub Signed-off-by: Roger Sheen --- release-notes/index.dita | 593 ++++++++++----------------------------- 1 file changed, 148 insertions(+), 445 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 9750592d..e539dcc6 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -1,15 +1,14 @@ - + DITA Open Toolkit <keyword keyref="release"/> Release Notes Release Notes - DITA Open Toolkit is a maintenance release that fixes issues - reported in DITA-OT , which includes . + DITA Open Toolkit includes .

          @@ -26,254 +25,9 @@ - - DITA-OT <keyword keyref="maintenance-version"/> - <ph outputclass="small text-muted">released October 21, 2025</ph> - - -

          -

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

          -
            - -
          • In DITA-OT 4.3.3, filtered, flagged, or duplicated topics were not copied to the temporary - directory, which caused builds to fail. The merge map parser and force unique filter modules have been - updated to ensure that attributes are correctly applied, so the topics are processed as intended. - #4701, - #4704, - #4708 -
            • -
          -

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

          -
          - -           - - - DITA-OT 4.3.4 - <ph outputclass="small text-muted">released July 30, 2025</ph> - - -
          -

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

          -
            - -
          • In earlier versions, links to content outside the map directory were not generated correctly in - HTML5 output when the nav-toc parameter was set to or - and the generate.copy.outer parameter was set to - to shift the output directory. Processing now follows topics and common stylesheets to - their new locations and writes links with correct paths even if the folders move. - #4478, - #4641, - #4667, - #4675 -
            • -
          • Additional tests have been added to verify the correct behavior of the - nav-toc parameter, and existing tests have been consolidated and parameterized for - easier maintenance. - #4660 -
            • -
          • Unit tests have been updated to resolve Windows-specific issues with line endings, file path - separators, and temporary file mappings. - #4662 -
            • -
          -

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

          -
          -           -           - - - DITA-OT 4.3.3 - <ph outputclass="small text-muted">released June 22, 2025</ph> - - -
          -

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

          -
            - -
          • Earlier versions of DITA-OT did not always cascade map-level attributes such as - format or scope correctly. Processing has been updated to ensure that - map metadata cascades as mandated by §2.2.4.4 of the - . - #4645 -
            • -
          -

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

          -
          -           -           - - - DITA-OT 4.3.2 - <ph outputclass="small text-muted">released June 5, 2025</ph> - - -
          -

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

          -
            - -
          • The GitHub release workflow was updated in DITA-OT 4.3.1 to build Docker images for both - linux/amd64 and linux/arm64 architectures, but this caused errors in - GitHub Actions as reported in - dita-ot-action#11. The release workflow has been updated to use the official Docker actions, which - support multi-platform builds and push the resulting platform-specific images to Docker Hub. - #4609 -
            • -
          • Table processing has been updated to improve handling for broken tables. If the - morerows attribute value is not an integer, strict processing mode will now report an - exception. If a row has fewer columns than the preceding row, processing will continue instead of failing - with a Java exception. - #4620, - #4628 -
            • -
          • Earlier versions of the map-first pre-processing routines in preprocess2 did - not apply stylesheets and parameters that were passed to the mapref processing phase by - custom plug-ins. The mapref module configuration has been updated to ensure that - preprocess2 respects the same parameters as the original pre-processing routine. - #4624, - #4625 -
            • -
          • Several dependencies have been upgraded to include the latest utility versions and fix security issues in - bundled libraries. - #4632 -
              -
            • Apache Commons IO 2.19.0
              • -
            • ICU4J 77.1
              • -
            • Guava 33.4.8-jre
              • -
            • Jackson data binding library 2.19.0
              • -
            • Jing 20241231
              • -
            • Logback Classic Module 1.5.18
              • -
            • Saxon 12.7
              • -
            • SLF4J 2.0.17
              • -
            • XML Resolver 5.3.3
              • -
            -
            • -
          • The bundled version has been updated to 2.11, which includes - PDFBox 3 and the latest versions of the and libraries. - #4623, - #4634 -

            (For details on recent changes, see the - .)

            -
            • -
          -

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

          -
          -           -           - - - DITA-OT 4.3.1 - <ph outputclass="small text-muted">released March 23, 2025</ph> - - -
          -

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

          -
            - -
          • DITA-OT 4.2 and later versions produced broken links in the navigation ToC when the - copy-to attribute was defined on topic references, or the - force-unique option was used. Generated temporary file names were used instead of - the copy-to attribute value. The copy-to attribute value is now respected - to ensure the correct links are written to the ToC. - #4564, - #4569 -
            • -
          • DITA-OT 4.3 included a regression bug that generated output in the out - subdirectory of the DITA-OT installation directory if the output location was not explicitly specified. In - this case, output is now generated in the out subdirectory of the current directory as - in DITA-OT 4.2.4 and earlier versions. - #4589, - #4594 -
            • -
          • The new validate subcommand introduced in DITA-OT 4.3 can now also be run by - setting the -f or --format options to validate. - The dita command line interface has also been updated to prevent conflicts between the - validate subcommand and the existing validate parameter. - #4590, - #4592, - #4602, - #4603 -
            • -
          • DITA-OT Docker images can now be built for both 64-bit Linux AMD and ARM architectures. No - changes are required to benefit from this enhancement. Docker should automatically select the image that - corresponds to the current machine architecture. - #4593 -
            • -
          • Earlier versions of DITA-OT generated invalid nested paragraphs in HTML output when the - lines element was used in a paragraph. Processing has been updated to ensure that - lines content is treated as a block element and rendered in separate paragraphs. - #4596, - #4599 -
            • -
          • Earlier versions of DITA-OT miscalculated the base directory when publications included - resource-only topics that were outside of the root map directory. Resource-only topics are now ignored in - this process to ensure that relative paths between resources are generated correctly. - #4606 -
            • -
          • Several dependencies have been upgraded to include the latest utility versions and fix security issues: -
              -
            • Ant 1.10.15 - #4595 -
              • -
            • Logback 1.5.17 - #4588 -
              • -
            • Saxon 12.5 - #4595 -
              • -
            -
            • -
          -

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

          -
          -           -           - - + DITA-OT <keyword keyref="release"/> - <ph outputclass="small text-muted"> released February 15, 2025</ph> + <!--<ph outputclass="small text-muted"> released February 1, 2026</ph>--> @@ -285,181 +39,108 @@

          DITA Open Toolkit Release includes - new init and validate subcommands that can be used to - set up projects from a template and check files for errors before publishing. You can now publish multiple - formats on the command line at once, add raw DITA to Markdown files, and publish bookmaps with PDF - themes.

          + something old, something new, something borrowed, and something blue.

          - - -
          - <b outputclass="badge badge-primary">Preview</b> Init subcommand -

          The new init subcommand initializes a project with files from a template. - #4509, - #4523 -

          -

          The initial implementation is a preview feature designed to illustrate how project templates work. You can - use templates as a starting point for new publications with required metadata, media assets, or custom - stylesheets, or provide examples of your organization’s preferred markup.

          +
          +
            -
          • For a list of available templates, run - init - --list
            • -
          • To add files from a template to the current directory, run - init - template
            • -
          -

          - Sample project templates are provided in the - new - org.dita.init plug-in. If you have a common project structure that would be useful - beyond your organization, you can contribute new templates to future DITA-OT versions, or create a custom - plug-in with company-specific project templates. -
          - -
          - Validate subcommand -

          A new validate subcommand can be used to check input files for errors before - publishing. - #4397, - #4400 -

          -

          This command runs the pre-processing routines in strict mode and reports any errors or warnings. This is - ideal for continuous integration scenarios, as it allows you to quickly check contributions for errors without - building output.

          -

          A new depend.validate extension point defines an Ant target to run with the - dita validate subcommand after pre-processing, so you can extend the default validation - mechanisms with your own checks.

          -
          - -
          - Multiple output formats from CLI -

          You can now publish multiple formats at once from a single dita command - sequence. - #4486

          -

          To produce several output formats from a single build, pass the --format option for each - transformation, or use the -f shorthand. For example: - -i sample.ditamap -f html5 -f pdf - The result will be the same as if you had issued separate commands for each format: - --input=sample.ditamap --format=html5 - --input=sample.ditamap --format=pdf -

          -

          This can be used as a simple alternative to a DITA-OT - project file that defines multiple deliverables.

          -
          - -
          - Lightweight DITA and Markdown updates -

          The org.lwdita plug-in has been updated to version , - which includes a series of bug fixes and support for additional DITA constructs in Markdown input, - including:

          -
            -
          • Language identifiers in fenced code blocks can now be processed with an optional prefix to enable syntax - highlighting in environments that require different keywords. For example, if Markdown files contain code - blocks with JavaScript code, they may start with ```js to display the code block with - syntax highlighting on GitHub. The plug-in can now add a prefix like language- to the DITA - outputclass value, included in HTML5 as class="language-js" for - with libraries like - . - #228 -
            • -
          • Admonition types are no longer case-sensitive, so both !!! note and !!! - Note will be rendered as DITA note elements, regardless of the - capitalization of the type keyword. - #229 -
            • -
          • If you need to include DITA content that has no equivalent markup in - , you can now use raw DITA XML directly in Markdown files. You can use - this approach to include things like xmlelement or - hazardstatement, which would otherwise be impossible to express in Markdown. - #217 -
            • -
          • Earlier versions would crash when processing Markdown files that did not begin with a heading. These files - are now converted to valid DITA with an empty title element, and an error message - appears in the log to aid in debugging. - #223 +
          • Support for DITA 2.0 keytext + #4644 +
            • +
          • Add directed graph for URIs + #4716
          -
          - -
          - <b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates -

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

          -
            -
          • -
          -

          - -

          -
          Enhancements and changes

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

          - +
            -
          • To reduce page load times, HTML5 output now uses - lazy loading for external images. - #4001, - #4005 - Local and peer image resources are loaded eagerly as in previous versions, but images defined with - scope="external" are now output with the loading - attribute set to "lazy" by default. A new set-image-loading template mode - allows custom plug-ins to override the default behavior if necessary.
            • -
          • The Java code for the map-first pre-processing routines now includes Javadoc comments to - document how the various stages are implemented. This documentation is not published separately, but is - available to developers who need to extend map processing or topic processing in custom plug-ins. Many - development environments extract and display the Javadoc information while viewing the source code. - #4404 -
            • -
          • The Java code has been modernized to use more standard library features and reduce dependencies - on external libraries, and restructured with automatic refactoring tools to make it easier to read and - maintain. - #4407, - #4441, - #4442, - #4444, - #4498 -
            • -
          • A new DOTJ088E error message makes it easier to identify XML parsing - exceptions in the log. - #4408 - The error appears when the input is in some way invalid but can still be parsed. The message content begins - with “XML parsing error:” and provides additional context from the parser in the - reason. As with other error messages, custom plug-ins may override the message - content or severity.
            • -
          • DITA-OT uses the Xerces SecurityManager to protect against the so-called - “billion - laughs attack”, an entity expansion technique that can cause XML parsers to run out of memory and - overload the CPU when parsing maliciously crafted files. DITA-OT will now stop parsing and report an error - when processing any files that exceed the entity limit imposed by the security manager library. - #4542, - #4556 -
            • -
          • Several bundled dependencies have been upgraded to the latest versions: -
              -
            • 2.10 (including the and - libraries) - #4519, - #4565 -
              • -
            +
          • Add stacktrace CLI option + #4579 +
            • +
          • Add support for multiple deliverable options + #4583 +
            • +
          • Move simple DITA 1.3 chunking to DITA 2.0 chunking module + #4600 +
            • +
          • Support HTML5 attribute group passthrough (#4488) + #4630 +
            • +
          • Refactor keyref parser + #4637 +
            • +
          • Cache topic IDs in keyref processing + #4638 +
            • +
          • Fix test class name + #4657 +
            • +
          • Use Files methods to create file streams + #4663 +
            • +
          • Add unit tests for coderef + #4664 +
            • +
          • Upgrade XSpec + #4665 +
            • +
          • #4447 follow-up /refactor_gradle + #4666 +
            • +
          • fix missing task description in xhtml build + #4672 +
            • +
          • Improve integration test results + #4673 +
            • +
          • refactor integration tests, modularize, rename + #4676 +
            • +
          • Intorduce more uplevels tests + #4677 +
            • +
          • check output image paths in integration tests + #4678 +
            • +
          • fix overlapping paths in integration test folders + #4679 +
            • +
          • Clean CleanPreprocessModule + #4680 +
            • +
          • Refactor clean preprocess + #4684 +
            • +
          • unify @BeforeAll method names in tests + #4690 +
            • +
          • Improve chunk processing + #4711 +
            • +
          • Update to Saxon 12.9 + #4712 +
            • +
          • Generic refactoring + #4718 +
            • +
          • Refactor intergrator + #4724 +
            • +
          • Add support for OASIS linktitle and navtitle elements + #4734 +
            • +
          • Update to Saxon-HE 12.9 + #4739
          @@ -468,19 +149,48 @@ Bug fixes

          DITA Open Toolkit Release provides fixes for the following bugs:

          - +
            -
          • In earlier versions, installing a plug-in from a path that contained the at-sign character - “@” failed with an InvalidArgumentException. The implementation has been - updated to ensure these paths are handled correctly. - #4354, - #4558 -
            • -
          • Earlier versions issued the DOTJ037W twice when running transformations with - the validate parameter set to false. This warning has been moved from - the Java code to Ant, which ensures that it only appears once for each transformation. - #4377, - #4396 +
          • NullPointerException when using the root-chunk-override with the new DITA 2.0 "combine" value + #4036 +
            • +
          • DITAVAL "passthough" action does not work for profiling applied to top-level (root) topic element + #4464 +
            • +
          • DITAVAL "passthough" action does not work for profiling applied to an attribute group + #4488 +
            • +
          • NullPointerException with --root-chunk-override=combine and xref in Dita 2.0 content + #4511 +
            • +
          • SAXParseException with --root-chunk-override=combine and table in Dita 2.0 content + #4513 +
            • +
          • support HTML5 attribute passthrough on root topic elements (#4464) + #4639 +
            • +
          • fix node executable path on Windows + #4688 +
            • +
          • DITA 2.0: HTML5 ignores navtitle element + #4695 +
            • +
          • Fix DITA 2.0 root map chunk + #4698 +
            • +
          • Fix force unique filter attribute stack + #4705 +
            • +
          • Fix attribute stack bug + #4706 +
            • +
          • Remove stale `args.logdir` reference from test code + #4733 +
            • +
          • Fix namespace prefix bug in move links + #4738
          @@ -489,21 +199,21 @@ Contributors

          DITA Open Toolkit Release includes by the following people:

          - + NOTE: This lists contributions to the core toolkit, not docs.
          1. Jarno Elovirta
            2. -
          2. Julien Lacour
            3. -
          3. Robert D Anderson
            4. +
          4. Dávid Bertalan
          5. Roger Sheen
            6. -
          6. Andrei Pomacu
            7. +
          7. Robert D Anderson
          8. Chris Papademetrious
            9. -
          9. Jason Fox
            10. - +
          10. Julien Lacour
            11. +
          11. Joshua Johnson
            12. +
          12. Gregor Latuske

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

          @@ -511,21 +221,12 @@
          Documentation updates -

          The documentation for DITA Open Toolkit Release has been reorganized to simplify - the navigation in HTML versions and reduce the number of parts in PDF output. All of the content from previous - versions is still available, though arranged slightly differently. The diagram in - shows the previous structure on the left, and the new locations on the - right.

          - - DITA-OT <keyword keyref="release"/> navigation changes - - -

          +

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

          @@ -535,12 +236,14 @@
          1. Roger Sheen
          2. Jarno Elovirta
            3. -
          3. Lief Erickson
            4. -
          4. Stefan Weil
            5. +
          5. Darrenn Jackson
            6. +
          6. Dávid Bertalan
            7. +
          7. Jeremy Jeanne
            8. +
          8. Stefan Jung

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

          From d3431d4c7fe77d6c94de4d05c8b66f2b71d2e681 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Wed, 21 Jan 2026 22:28:25 +0100 Subject: [PATCH 07/36] Add recently resolved issues to enhancements list Signed-off-by: Roger Sheen --- release-notes/index.dita | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/release-notes/index.dita b/release-notes/index.dita index e539dcc6..af4c1dc5 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -76,6 +76,12 @@
        1. Support HTML5 attribute group passthrough (#4488) #4630
          2. +
        2. add a CSS comment explaining why 'display: inline' is applied to note body (#4629) + #4631 +
          3. +
        3. Rename DITAVAL @outputclass to @add-outputclass + #4635 +
        4. Refactor keyref parser #4637
          5. From bc1bcc80e82433d42594b22676d96628db3edaa3 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Wed, 21 Jan 2026 22:44:17 +0100 Subject: [PATCH 08/36] Prepare initial feature section summaries Signed-off-by: Roger Sheen --- release-notes/index.dita | 42 ++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index af4c1dc5..a8e3939d 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -45,16 +45,42 @@ >something old, something new, something borrowed, and something blue.

          -
          - + + +
          + DITA 2.0 keytext +

          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:

            -
          • Support for DITA 2.0 keytext - #4644 -
            • -
          • Add directed graph for URIs - #4716 -
            • +
          • 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.

          +
          + +
          + URI dependency tracking +

          A new directed graph data structure has been added to track dependencies between resources identified by URI. + #4716 +

          +

          This internal infrastructure improvement provides 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.

          From 0b70d3451c3c556babc495bfe3b2337feeb6aedb Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Wed, 21 Jan 2026 23:05:55 +0100 Subject: [PATCH 09/36] Summarize enhancements and bugfixes Signed-off-by: Roger Sheen --- release-notes/index.dita | 204 +++++++++++++++++++++++---------------- 1 file changed, 119 insertions(+), 85 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index a8e3939d..b6cba428 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -90,90 +90,111 @@ existing features:

            -
          • Add stacktrace CLI option +
          • 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
            • -
          • Add support for multiple deliverable options +
          • 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
            • -
          • Move simple DITA 1.3 chunking to DITA 2.0 chunking module +
          • 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
            • -
          • Support HTML5 attribute group passthrough (#4488) +
          • 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. #4630
            • -
          • add a CSS comment explaining why 'display: inline' is applied to note body (#4629) +
          • 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 explain this styling choice. #4631
            • -
          • Rename DITAVAL @outputclass to @add-outputclass +
          • 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
            • -
          • Refactor keyref parser +
          • The keyref parser has been refactored to improve code quality and prepare for future feature + additions. #4637
            • -
          • Cache topic IDs in keyref processing +
          • 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
            • -
          • Fix test class name - #4657 -
            • -
          • Use Files methods to create file streams - #4663 -
            • -
          • Add unit tests for coderef - #4664 -
            • -
          • Upgrade XSpec - #4665 -
            • -
          • #4447 follow-up /refactor_gradle - #4666 -
            • -
          • fix missing task description in xhtml build - #4672 -
            • -
          • Improve integration test results - #4673 -
            • -
          • refactor integration tests, modularize, rename - #4676 -
            • -
          • Intorduce more uplevels tests - #4677 -
            • -
          • check output image paths in integration tests - #4678 -
            • -
          • fix overlapping paths in integration test folders - #4679 -
            • -
          • Clean CleanPreprocessModule - #4680 -
            • -
          • Refactor clean preprocess - #4684 -
            • -
          • unify @BeforeAll method names in tests - #4690 -
            • -
          • Improve chunk processing +
          • 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
            • -
          • Update to Saxon 12.9 - #4712 -
            • -
          • Generic refactoring - #4718 -
            • -
          • Refactor intergrator - #4724 -
            • -
          • Add support for OASIS linktitle and navtitle elements +
          • 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
            • -
          • Update to Saxon-HE 12.9 +
          • 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 +
            • +
          • Several internal code improvements have been made to enhance 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 +
              • +
            +
          @@ -183,47 +204,60 @@

          DITA Open Toolkit Release provides fixes for the following bugs:

            -
          • NullPointerException when using the root-chunk-override with the new DITA 2.0 "combine" value +
          • 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
            • -
          • DITAVAL "passthough" action does not work for profiling applied to top-level (root) topic element - #4464 +
          • 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
            • -
          • DITAVAL "passthough" action does not work for profiling applied to an attribute group +
          • DITAVAL passthrough actions were not being applied to profiling attribute + groups in HTML5 output. For example, a value like audience="llm(keep)" would not generate + the expected passthrough attribute, even when a matching prop rule was defined. + Processing has been updated so passthrough attributes are created using the group name. #4488
            • -
          • NullPointerException with --root-chunk-override=combine and xref in Dita 2.0 content +
          • 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
            • -
          • SAXParseException with --root-chunk-override=combine and table in Dita 2.0 content - #4513 -
            • -
          • support HTML5 attribute passthrough on root topic elements (#4464) - #4639 +
          • 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
            • -
          • fix node executable path on Windows +
          • The Gradle build configuration has been updated to correctly locate the Node.js executable path + on Windows systems. #4688
            • -
          • DITA 2.0: HTML5 ignores navtitle element +
          • 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
            • -
          • Fix DITA 2.0 root map chunk +
          • Combine chunking for the root map in DITA 2.0 has been fixed. #4698
            • -
          • Fix force unique filter attribute stack - #4705 -
            • -
          • Fix attribute stack bug +
          • 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
            • -
          • Remove stale `args.logdir` reference from test code +
          • 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
            • -
          • Fix namespace prefix bug in move links - #4738 -
          From 240fdee53d0e17ce4c8ddb0fba935cce0470e477 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Wed, 21 Jan 2026 23:23:10 +0100 Subject: [PATCH 10/36] Move DITA 2.0 enhancements to feature section Signed-off-by: Roger Sheen --- release-notes/index.dita | 44 ++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index b6cba428..766fb3bc 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -48,7 +48,7 @@
          - DITA 2.0 keytext + DITA 2.0 support

          DITA-OT now supports the DITA 2.0 keytext element and implements the updated

          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-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 +

          @@ -102,13 +123,6 @@ specific deliverables without publishing all deliverables defined in the project. #4583 -
        5. 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 -
        6. 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 @@ -122,12 +136,6 @@ comment has been added to explain this styling choice. #4631
          7. -
        7. 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 -
        8. The keyref parser has been refactored to improve code quality and prepare for future feature additions. #4637 @@ -141,14 +149,6 @@ refactoring work lays the groundwork for future support of select tokens in DITA 2.0 chunk processing. #4711
          9. -
        9. 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 -
        10. Saxon has been updated to version 12.9, which includes minor bug fixes. #4712, #4739 From 8292b516922ce4036af9b3bbc90ab79ec9a99814 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 22 Jan 2026 00:40:05 +0100 Subject: [PATCH 11/36] Structure DITA 2.0 feature section as list Signed-off-by: Roger Sheen --- release-notes/index.dita | 126 ++++++++++++++++++++++----------------- 1 file changed, 72 insertions(+), 54 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 766fb3bc..d81232d5 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -47,50 +47,68 @@ -
          - DITA 2.0 support -

          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:

          +
          + <b outputclass="badge badge-primary">Preview</b> DITA 2.0 support +

          In addition to the + 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 (as of ).

            -
          • 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).
            • +
          • +

            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 +

          -

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

          @@ -145,19 +163,19 @@ definitions that include a topic ID (such as href="topic.dita#id") are not affected. #4638
          11. -
        11. 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 -
          12. -
        12. Saxon has been updated to version 12.9, which includes minor bug fixes. - #4712, - #4739 -
          13. -
        13. 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 +
        14. Several bundled dependencies have been upgraded to the latest versions: +
            +
          • 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 +
            • +
          15. -
        15. Several internal code improvements have been made to enhance code quality, test coverage, and +
        16. Various internal code improvements have been made for better code quality, test coverage, and maintainability:
          • Test class names now consistently use a Test suffix From dd7958a52a547e4bb59d433de5002befb26fa62d Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 22 Jan 2026 00:45:02 +0100 Subject: [PATCH 12/36] Draft release summary: focus on DITA 2.0 features Signed-off-by: Roger Sheen --- release-notes/index.dita | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index d81232d5..36425589 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -38,11 +38,10 @@
            -

            DITA Open Toolkit Release includes - something old, something new, something borrowed, and something blue.

            +

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

            From 1bac2afd4a91e7dfebc9be7ce5d0a93511e6df79 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 22 Jan 2026 01:10:04 +0100 Subject: [PATCH 13/36] Add missing entry for section title bugfix https://github.com/dita-ot/dita-ot/pull/4731 Signed-off-by: Roger Sheen --- release-notes/index.dita | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/release-notes/index.dita b/release-notes/index.dita index 36425589..a043eb5b 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -271,6 +271,13 @@ #4705, #4706
            • +
          • 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 +
          • 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 From dd20cbf58540be89aad0d804fa81118c8d950838 Mon Sep 17 00:00:00 2001 From: Lief Erickson Date: Wed, 21 Jan 2026 23:14:57 -0600 Subject: [PATCH 14/36] Add DITA-OT Day 2025 videos (cherry picked from lief-erickson/dita-ot-docs@d67a4c6: feature/dita-ot-day-2025) Signed-off-by: Lief Erickson Signed-off-by: Roger Sheen --- resources/dita-ot-day-video-keys.ditamap | 1 + .../dita-ot-day-2025-keys.ditamap | 185 ++++++++++++++++++ resources/source-files.ditamap | 1 + topics/dita-ot-day-2025.ditamap | 27 +++ topics/dita-ot-day-videos-intro-2025.dita | 17 ++ topics/dita-ot-day-videos.ditamap | 1 + 6 files changed, 232 insertions(+) create mode 100644 resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap create mode 100644 topics/dita-ot-day-2025.ditamap create mode 100644 topics/dita-ot-day-videos-intro-2025.dita diff --git a/resources/dita-ot-day-video-keys.ditamap b/resources/dita-ot-day-video-keys.ditamap index 421868d9..6587bf13 100644 --- a/resources/dita-ot-day-video-keys.ditamap +++ b/resources/dita-ot-day-video-keys.ditamap @@ -11,4 +11,5 @@ + diff --git a/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap b/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap new file mode 100644 index 00000000..6d770825 --- /dev/null +++ b/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap @@ -0,0 +1,185 @@ + + + + + DITA-OT Day 2025 + + + Future Plans + No description. + DITA-OT Day Team + + + + + Single Source Publishing? Bury the Hatchet with DITA-OT + Our team has been leveraging DITA-OT for quite some time, and it has become an invaluable tool in our single-source publishing workflow. + Snehal Borole, Ritu Saxena + + + + + Automating Compliance Verification for Documentation Standards Using AI + Ensuring that technical documentation adheres to industry standards, such as IEC 60335, can be a daunting task given the extensive and detailed nature of these standards. This presentation explores an innovative approach to automate the compliance verification process using AI agents. + Alex Jitianu + + + + + Providing content to AI engines using DITA OT plugins + Content from a DITA XML project can be used to provide information to an AI engine. In this presentation I will present two possible DITA OT plugin implementation: A DITA Open Toolkit plugin which creates fine tune material for AI engines using style guides.A DITA Open Toolkit plugin which uploads generated content to a vector store to be used by an AI Assistant.Apply AI checks to preprocessed DITA XML content.Preprocessing content using AI The presentation will also give us the possibility to look into how DITA-OT plugins are built. + Radu Coravu + + + + + DITA-OT in the Age of AI: Bridging Technical Writing and Artificial Intelligence + The DITA Open Toolkit (DITA-OT) empowers technical writing by transforming traditional authoring practices into strategic content development. Learn how Technical Writers can create content with specifics to feed AI systems with high-quality, context-rich data. This enhances AI RAG (Retrieval-Augmented Generation) models and LLMs (Large Language Models) by providing them with accurate, intent-specific information for improved training and response delivery. This session explores the critical role of DITA-OT in enabling proactive content authoring practices that align technical writing with AI enablement. Key discussion points include: How DITA-OT facilitates the transformation of structured content into AI-ready assets. The importance of metadata and taxonomy in enhancing context and intent for AI-driven applications. Best practices for transitioning from reactive to proactive content strategies using DITA-OT. Attendees will gain insights into how DITA-OT integrates technical writing with AI, driving superior user experiences and maximizing the value of knowledge-based systems. + Amit Siddhartha + + + + + Building an Ant based environment around the DITA OT + In our customer deployments we have built an Ant-based environment around the DITA OT which allows us to extract and prepare the content before it's sent to OT processing. We will discuss how this design could be replicated on disk without the use of a CCMS. + Eric Sirois + + + + + Learning Assessment QTI Output + Working with DITA in a learning/training group, a challenging content type to work with is the <learningAssessment> topic. Sourcing these questions in DITA is ideal to facilitate reuse across content types and to allow them to be output to multiple formats. For many learning/training groups, the primary output of learning assessment content is a platform that delivers and scores electronic exams. Most of these systems work with an import of QTI (Question & Test Interoperability) XML. While each system’s implementation of QTI varies, there is a common structure that can be used as a starting point. + Brianna Stevens-Russell + + + + + Replacement keyspace constructor for Open Toolkit + As of OT 4.2, the key space construct implementation works fine for smaller key spaces but fails with larger key spaces (10s or 100s of 1000s of keys). This paper presents an alternative key space construction implementation that handles arbitrarily large key spaces with reasonable performance and memory consumption. + Eliot Kimber + + + + + Welcome to DITA-OT Community: Where Code meets Passion + Imagine a scenario where you are facing challenges while working with DITA Open Toolkit. You search for solutions online, check various forums and groups, but find no answers. You feel like you have no one else to turn to. However, there’s one group you haven’t reached out to yet – the DITA-OT community. A “hidden” network of DITA-OT experts, eager to share their knowledge and help you solve your problems. But how do you find them? Who are they? Who belongs to the DITA-OT community? What do we truly know about each other? + Justyna Hietala + + + + + Documentation Developments + This talk provides an overview of the recent changes to the DITA-OT documentation and project website, points out open issues, highlights ideas for future improvements, and closes with room for suggestions from the community and a call for contributions. + Roger Sheen + + + + + DITA-OT and DITA 2.0: who’s done what now? + DITA-OT is not part of the OASIS standards organization, but the project does its best to keep up with changes in the standard. In this session, we’ll talk about what we expect from OASIS with DITA 2.0, what you can already make use of in DITA-OT, and what you can do to help make the rest of the features a reality. + Robert Anderson + + + + + DITA-OT New Features and Enhancements + We'll go through the list of features and enhancements made to the DITA OT in the newest releases. + Jarno Elovirta + + + + + News and announcements + No description. + DITA-OT Day Team + + + + + Welcome and sponsor presentation + No description. + Sponsor Presentation + + + diff --git a/resources/source-files.ditamap b/resources/source-files.ditamap index 5c201359..eed5de1e 100644 --- a/resources/source-files.ditamap +++ b/resources/source-files.ditamap @@ -35,6 +35,7 @@ + diff --git a/topics/dita-ot-day-2025.ditamap b/topics/dita-ot-day-2025.ditamap new file mode 100644 index 00000000..a68bcf3f --- /dev/null +++ b/topics/dita-ot-day-2025.ditamap @@ -0,0 +1,27 @@ + + + + + DITA-OT Day 2025 + + + 2025 Copenhagen + Copenhagen 2025 + + + + + + + + + + + + + + + + + + diff --git a/topics/dita-ot-day-videos-intro-2025.dita b/topics/dita-ot-day-videos-intro-2025.dita new file mode 100644 index 00000000..79c497a4 --- /dev/null +++ b/topics/dita-ot-day-videos-intro-2025.dita @@ -0,0 +1,17 @@ + + + + + DITA-OT Day Conference – Copenhagen 2025 + February 16, 2025 in Copenhagen, Denmark. + + + + DITA-OT Day 2025 videos + + + + +

            + + diff --git a/topics/dita-ot-day-videos.ditamap b/topics/dita-ot-day-videos.ditamap index 0d9ee3d0..8ae03596 100644 --- a/topics/dita-ot-day-videos.ditamap +++ b/topics/dita-ot-day-videos.ditamap @@ -5,6 +5,7 @@ DITA-OT Day Videos + From c82616e080f33ae911376cdfe3fd8bc83382144d Mon Sep 17 00:00:00 2001 From: Jarno Elovirta Date: Thu, 22 Jan 2026 18:12:53 +0200 Subject: [PATCH 15/36] Add info on JSON log format (#611) Co-authored-by: Roger Sheen Signed-off-by: Roger Sheen Signed-off-by: Jarno Elovirta --- parameters/dita-command-arguments.dita | 12 ++++++++++++ topics/logging.dita | 5 +++++ 2 files changed, 17 insertions(+) diff --git a/parameters/dita-command-arguments.dita b/parameters/dita-command-arguments.dita index 4fa009a0..a6769d72 100644 --- a/parameters/dita-command-arguments.dita +++ b/parameters/dita-command-arguments.dita @@ -376,6 +376,18 @@ --verbose option (or -v). + + + --logger=json + + +

            Generate a structured log in JSON format. Each log message generates a JSON object on its own line. JSON + logging disables colored output.

            +

            If log is written to a file with --logfile, the log will be generated as a JSON array + where each log message is a JSON object as an array item.

            + + --no-color diff --git a/topics/logging.dita b/topics/logging.dita index 6dc2863e..e0a9a01b 100644 --- a/topics/logging.dita +++ b/topics/logging.dita @@ -56,6 +56,11 @@ --logfile=file and specify the path to the log file.

            Unless an absolute path is specified, the value will be interpreted relative to the current directory.

            • +
          • Use dita + --logger=json to generate a structured log in JSON format. Each + log message generates a JSON object on its own line. +

            If log is written to a file with --logfile, the log will be generated as a JSON + array where each log message is a JSON object as an array item.

          From 7bc83fdc9dd0d85125807b8fedb3daf23c1a0dfc Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sat, 13 Dec 2025 23:11:57 +0100 Subject: [PATCH 16/36] Add passthrough action for importance attribute This will allow us to mark deprecated parameters and extension points per https://github.com/dita-ot/docs/issues/648#issuecomment-3649715352 Signed-off-by: Roger Sheen --- resources/html.ditaval | 1 + resources/pdf.ditaval | 1 + resources/site.ditaval | 1 + 3 files changed, 3 insertions(+) diff --git a/resources/html.ditaval b/resources/html.ditaval index d6c51135..834cc486 100644 --- a/resources/html.ditaval +++ b/resources/html.ditaval @@ -3,4 +3,5 @@ + diff --git a/resources/pdf.ditaval b/resources/pdf.ditaval index 82a03624..372b0a01 100644 --- a/resources/pdf.ditaval +++ b/resources/pdf.ditaval @@ -3,4 +3,5 @@ + diff --git a/resources/site.ditaval b/resources/site.ditaval index b620aa17..5a0db825 100644 --- a/resources/site.ditaval +++ b/resources/site.ditaval @@ -3,5 +3,6 @@ + From 2d167e8d1b9645ddcc9fd564b1baf64f89f5eefb Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 1 Jan 2026 14:17:03 +0100 Subject: [PATCH 17/36] Mark deprecated elements in HTML output Signed-off-by: Roger Sheen --- resources/dita-ot-doc.css | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/resources/dita-ot-doc.css b/resources/dita-ot-doc.css index 6e1ae32e..c2d91668 100644 --- a/resources/dita-ot-doc.css +++ b/resources/dita-ot-doc.css @@ -789,6 +789,24 @@ pre code { font-size: 0.8125rem; } +/* Mark deprecated elements */ + +[data-importance='deprecated'], +[data-importance='deprecated'] + dd, +[data-importance='deprecated'] .parmname { + color: var(--code-color); +} + +dt[data-importance='deprecated'] .parmname::after { + border-radius: 0.25rem; + content: 'DEPRECATED'; + font-size: 75%; + margin-left: 0.5em; + padding: 0.25em 0.4em; + background-color: var(--code-color); + color: var(--secondary-bg); +} + /**************************************** Headings ****************************************/ From 7200083775243056660b332fe630014c0c46b121 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 1 Jan 2026 14:24:36 +0100 Subject: [PATCH 18/36] Simplify and align deprecation references Signed-off-by: Roger Sheen --- parameters/ant-parameters-details.dita | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/parameters/ant-parameters-details.dita b/parameters/ant-parameters-details.dita index 1badd09d..a16395d7 100644 --- a/parameters/ant-parameters-details.dita +++ b/parameters/ant-parameters-details.dita @@ -223,8 +223,7 @@ - This parameter is deprecated in favor of the args.filter - parameter. + This parameter is deprecated; use args.filter instead. @@ -522,8 +521,7 @@
          Corresponds to the XSLT parameter NOPARENTLINK. - This parameter is deprecated in favor of the args.rellinks - parameter. + This parameter is deprecated; use args.rellinks instead.
          @@ -747,9 +745,10 @@ The default value is the value of the args.draft parameter. - Corresponds to the XSLT parameter - publishRequiredCleanup.This parameter is deprecated in - favor of the args.draft parameter. + Corresponds to the XSLT parameter + publishRequiredCleanup. + This parameter is deprecated; use + args.draft instead.
          17. From c3e7c9d258c90191368a54d90ae63a734a7cb5d8 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 1 Jan 2026 14:34:52 +0100 Subject: [PATCH 19/36] Push deprecation details to `outputFile.base` #648 Signed-off-by: Roger Sheen --- parameters/ant-parameters-details.dita | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/parameters/ant-parameters-details.dita b/parameters/ant-parameters-details.dita index a16395d7..271868ac 100644 --- a/parameters/ant-parameters-details.dita +++ b/parameters/ant-parameters-details.dita @@ -711,15 +711,21 @@ . - + outputFile.base + + deprecated features + outputFile.base By default, the PDF file uses the base filename of the input .ditamap file. DITA maps - PDF file name + PDF file name + This parameter is deprecated since DITA-OT 3.0; use + args.output.base instead. + From 32e4712166c1ce3343929f46048dfc28fd45ed28 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 23 Jan 2026 00:27:10 +0100 Subject: [PATCH 20/36] Edit 2025 video descriptions Signed-off-by: Roger Sheen --- resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap b/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap index 6d770825..d9c1fe1d 100644 --- a/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap +++ b/resources/ditaotdaykeys/dita-ot-day-2025-keys.ditamap @@ -11,7 +11,6 @@ > Future Plans - No description. DITA-OT Day Team @@ -50,7 +49,7 @@ Providing content to AI engines using DITA OT plugins Content from a DITA XML project can be used to provide information to an AI engine. In this presentation I will present two possible DITA OT plugin implementation: A DITA Open Toolkit plugin which creates fine tune material for AI engines using style guides.A DITA Open Toolkit plugin which uploads generated content to a vector store to be used by an AI Assistant.Apply AI checks to preprocessed DITA XML content.Preprocessing content using AI The presentation will also give us the possibility to look into how DITA-OT plugins are built. + >Content from a DITA XML project can be used to provide information to an AI engine. In this presentation I will present two possible DITA OT plugin implementations: A DITA Open Toolkit plugin which creates fine tune material for AI engines using style guides. A DITA Open Toolkit plugin which uploads generated content to a vector store to be used by an AI Assistant. Apply AI checks to preprocessed DITA XML content.Preprocessing content using AI The presentation will also give us the possibility to look into how DITA-OT plugins are built. Radu Coravu From cd8315ca9b278755d818770e1f66456cbb3d66c7 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 00:10:17 +0100 Subject: [PATCH 21/36] Fix keyref for 2025 new features video topic Signed-off-by: Roger Sheen --- topics/dita-ot-day-2025.ditamap | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topics/dita-ot-day-2025.ditamap b/topics/dita-ot-day-2025.ditamap index a68bcf3f..2b89279d 100644 --- a/topics/dita-ot-day-2025.ditamap +++ b/topics/dita-ot-day-2025.ditamap @@ -11,7 +11,7 @@ - + From c024ba2051d515c8da4a667a1ab9b623d5b05ba4 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 11:55:05 +0100 Subject: [PATCH 22/36] Add missing issue link Signed-off-by: Roger Sheen --- release-notes/index.dita | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index a043eb5b..fa441d74 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -150,7 +150,8 @@
        17. 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 explain this styling choice. + comment has been added to the default stylesheets to explain this styling choice. + #4629, #4631
        18. The keyref parser has been refactored to improve code quality and prepare for future feature From eaf89b40c237476b356b0bc966ac3e4bfb10c7ea Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 14:03:02 +0100 Subject: [PATCH 23/36] Mark publish.required.cleanup as deprecated Signed-off-by: Roger Sheen --- parameters/ant-parameters-details.dita | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/parameters/ant-parameters-details.dita b/parameters/ant-parameters-details.dita index 271868ac..ebce4a58 100644 --- a/parameters/ant-parameters-details.dita +++ b/parameters/ant-parameters-details.dita @@ -742,15 +742,25 @@ formatter - + + publish.required.cleanup deprecated features + publish.required.cleanup + parameters publish.required.cleanup - - The default value is the value of the args.draft parameter. + Specifies whether draft-comment and required-cleanup elements are + included in the output. The allowed values are , and . + + The default value is the value of the args.draft parameter. Corresponds to the XSLT parameter publishRequiredCleanup. This parameter is deprecated; use From bfd498524791be78d4572220e0fa6de536b98c8a Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 14:26:35 +0100 Subject: [PATCH 24/36] Move DITA 2.0 updates to spec support for re-use Signed-off-by: Roger Sheen --- reference/dita-v2-0-support.dita | 61 +++++++++++++++++++++++++++++- release-notes/index.dita | 64 ++++---------------------------- 2 files changed, 67 insertions(+), 58 deletions(-) diff --git a/reference/dita-v2-0-support.dita b/reference/dita-v2-0-support.dita index 2cea93d0..50df36d8 100644 --- a/reference/dita-v2-0-support.dita +++ b/reference/dita-v2-0-support.dita @@ -187,7 +187,7 @@
          19. DITA-OT 4.3 -

          DITA-OT 4.3 adds support for additional DITA 2.0 features.

          +

          DITA-OT 4.3 added support for additional DITA 2.0 features.

          • HTML5 processing now supports the height and width attributes on the DITA 2.0 video element to ensure that videos are scaled correctly. @@ -199,6 +199,65 @@
          +
          + DITA-OT 4.4 +

          DITA-OT 4.4 adds support for additional DITA 2.0 features.

          +
            +
          • +

            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 +

            • +
          +
          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. diff --git a/release-notes/index.dita b/release-notes/index.dita index fa441d74..b29d398e 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -46,68 +46,18 @@ -
          - <b outputclass="badge badge-primary">Preview</b> DITA 2.0 support +
          + <b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates

          In addition to the 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 (as of ).

          -
            -
          • -

            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 -

            • + />).

            +
              +
            +

            +

          From 4cceac8a558cc1ca7df35f69e8d1efb9406fb3a7 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:02:19 +0100 Subject: [PATCH 25/36] Add previous release dates to 2.0 spec support Signed-off-by: Roger Sheen --- reference/dita-v2-0-support.dita | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/reference/dita-v2-0-support.dita b/reference/dita-v2-0-support.dita index 50df36d8..6130e185 100644 --- a/reference/dita-v2-0-support.dita +++ b/reference/dita-v2-0-support.dita @@ -17,7 +17,9 @@

          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.

          - DITA-OT 3.5 + DITA-OT 3.5 + <ph outputclass="small text-muted">released April 27, 2020</ph> +

          DITA-OT 3.5 provided an initial preview of DITA 2.0 features.

          • @@ -64,7 +66,9 @@
          - DITA-OT 3.6 + DITA-OT 3.6 + <ph outputclass="small text-muted">released December 19, 2020</ph> +

          DITA-OT 3.6 added support for additional DITA 2.0 features.

          • Where earlier DITA versions relied on the object element to embed media in DITA @@ -91,7 +95,9 @@
          - DITA-OT 3.7 + DITA-OT 3.7 + <ph outputclass="small text-muted">released January 17, 2022</ph> +

          DITA-OT 3.7 added support for additional DITA 2.0 features.

          • The new “combine” chunk action can be used to merge content into new output documents. @@ -152,7 +158,9 @@
          - DITA-OT 4.0 + DITA-OT 4.0 + <ph outputclass="small text-muted">released November 12, 2022</ph> +

          DITA-OT 4.0 added support for additional DITA 2.0 features.

          • The new “split” chunk action can be used to break content into new output documents. @@ -169,7 +177,9 @@
          - DITA-OT 4.1 + DITA-OT 4.1 + <ph outputclass="small text-muted">released June 22, 2023</ph> +

          DITA-OT 4.1 added support for additional DITA 2.0 features.

          • @@ -186,7 +196,9 @@
          - DITA-OT 4.3 + DITA-OT 4.3 + <ph outputclass="small text-muted"> released February 15, 2025</ph> +

          DITA-OT 4.3 added support for additional DITA 2.0 features.

          • HTML5 processing now supports the height and width attributes From 63576ee397286cd37d268340e803f921dd5d838e Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:05:02 +0100 Subject: [PATCH 26/36] Add 4.4 migration topic & re-use DITA 2.0 info Signed-off-by: Roger Sheen --- resources/source-files.ditamap | 1 + topics/migrating-to-4.4.dita | 39 ++++++++++++++++++++++++++++++++++ topics/migration.ditamap | 1 + 3 files changed, 41 insertions(+) create mode 100644 topics/migrating-to-4.4.dita diff --git a/resources/source-files.ditamap b/resources/source-files.ditamap index eed5de1e..fb190eae 100644 --- a/resources/source-files.ditamap +++ b/resources/source-files.ditamap @@ -115,6 +115,7 @@ + diff --git a/topics/migrating-to-4.4.dita b/topics/migrating-to-4.4.dita new file mode 100644 index 00000000..97973ce6 --- /dev/null +++ b/topics/migrating-to-4.4.dita @@ -0,0 +1,39 @@ + + + + + + Migrating to release 4.4 + + To 4.4 + + + DITA-OT 4.4 includes 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. + + +
            + This topic provides a summary of changes in DITA-OT 4.4 that may require modifications to custom stylesheets + or plug-ins. For more information on changes in this release, see the + . +
            + +
            + <b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates +

            In addition to the + 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 (as of ).

            + Consider updating your documents and/or customizations to take advantage of the new features and + prepare for the transition to DITA 2.0. +

            +

            +

            +

            + +

            + +             +             diff --git a/topics/migration.ditamap b/topics/migration.ditamap index 5e40af20..bba81717 100644 --- a/topics/migration.ditamap +++ b/topics/migration.ditamap @@ -4,6 +4,7 @@ Migrating customizations + From 828eb311715ea1fef9b1213c71b4d0fd4c8d8190 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:15:04 +0100 Subject: [PATCH 27/36] Update contributors lists based on latest commits Signed-off-by: Roger Sheen --- release-notes/index.dita | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index b29d398e..fd59a43f 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -248,8 +248,9 @@
          • Roger Sheen
          • Robert D Anderson
          • Chris Papademetrious
            • -
          • Julien Lacour
          • Joshua Johnson
            • +
          • Julien Lacour
            • +
          • Guillaume Delory
          • Gregor Latuske

        For the complete list of changes since the previous release, see the @@ -280,6 +281,7 @@

      • Darrenn Jackson
      • Dávid Bertalan
      • Jeremy Jeanne
        • +
      • Lief Erickson
      • Stefan Jung

        • For the complete list of documentation changes since the previous release, see the From b00dcff9e598fa30825ad524448f402780904298 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:30:00 +0100 Subject: [PATCH 28/36] Bump Saxon-HE to version 12.9 Upgrade Saxon-HE version in the key definition & Gradle build file to 12.9. See dita-ot/dita-ot#4739 for corresponding update in core repo. Signed-off-by: Roger Sheen --- build.gradle | 2 +- resources/key-definitions.ditamap | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/build.gradle b/build.gradle index 729ad205..512832c2 100644 --- a/build.gradle +++ b/build.gradle @@ -3,7 +3,7 @@ buildscript { mavenCentral() } dependencies { - classpath 'net.sf.saxon:Saxon-HE:10.6' + classpath 'net.sf.saxon:Saxon-HE:12.9' } } diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index f7b3a5fe..5b170467 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -173,7 +173,7 @@ - 12.7 + 12.9 From 7f54ac9621421b7e967786860a7dc8b7f941e05f Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:55:02 +0100 Subject: [PATCH 29/36] Remove mark highlight from release summary Signed-off-by: Roger Sheen --- release-notes/index.dita | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index fd59a43f..763e40f1 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -38,9 +38,9 @@

        -

        DITA Open Toolkit Release includes support - for additional features in the upcoming DITA 2.0 standard, including the keytext - and linktitle elements, new class attributes for navtitle, +

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

        From c1cab0781b2b2bc2fc213be10f38c22ed2c8c4c6 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 15:55:14 +0100 Subject: [PATCH 30/36] List updated docs topics in 4.4 Signed-off-by: Roger Sheen --- release-notes/index.dita | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/release-notes/index.dita b/release-notes/index.dita index 763e40f1..80d0c692 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -264,6 +264,23 @@
        Documentation updates +

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

        +
          +
        • +
          • +
        • +
          • +
        • + DITA-OT Day 2025 videos
          • +
        • +
          • +
        • +
          • +
        • +
          • +
        +

        For additional information on documentation issues resolved in DITA Open Toolkit Release , see the From 8e942852f62b844e1ef991e4f73305618890b985 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 16:30:00 +0100 Subject: [PATCH 31/36] Add entries for recently resolved issues in 4.4 Signed-off-by: Roger Sheen --- release-notes/index.dita | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/release-notes/index.dita b/release-notes/index.dita index 80d0c692..ae2e5a12 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -98,6 +98,10 @@ and ungrouped values belong to an implicit group named after the attribute. #4630

        • +
      • HTML5 output now 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 +
      • 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. @@ -222,6 +226,13 @@ #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 From b39fa9b7139fb991aa21fe20bacdcbec38a5dc8b Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 25 Jan 2026 17:17:30 +0100 Subject: [PATCH 32/36] Combine entries for HTML5 passthrough changes Signed-off-by: Roger Sheen --- release-notes/index.dita | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index ae2e5a12..62f05faf 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -78,6 +78,19 @@ 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 @@ -90,18 +103,6 @@ specific deliverables without publishing all deliverables defined in the project. #4583
          • -
        • 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. - #4630 -
          • -
        • HTML5 output now 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 -
        • 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. @@ -189,12 +190,6 @@ #4464, #4639
          • -
        • DITAVAL passthrough actions were not being applied to profiling attribute - groups in HTML5 output. For example, a value like audience="llm(keep)" would not generate - the expected passthrough attribute, even when a matching prop rule was defined. - Processing has been updated so passthrough attributes are created using the group name. - #4488 -
        • 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. From 070c86bfcc66126adbaa210d8d4f0a6034136d51 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 26 Jan 2026 00:30:00 +0100 Subject: [PATCH 33/36] Add entries for recently resolved issues in 4.4 Signed-off-by: Roger Sheen --- reference/dita-v2-0-support.dita | 21 ++++++++++++++ release-notes/index.dita | 47 +++++++++++++++++++++++++------ resources/key-definitions.ditamap | 2 +- 3 files changed, 61 insertions(+), 9 deletions(-) diff --git a/reference/dita-v2-0-support.dita b/reference/dita-v2-0-support.dita index 6130e185..e9cf6dde 100644 --- a/reference/dita-v2-0-support.dita +++ b/reference/dita-v2-0-support.dita @@ -268,6 +268,27 @@ these new elements. #4734

          • +
        • +

          DITA 2.0 grammar files have been updated to the latest draft versions from OASIS (as of ). 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
            • +
          +

      diff --git a/release-notes/index.dita b/release-notes/index.dita index 62f05faf..ff0756b1 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -8,7 +8,7 @@ - DITA Open Toolkit includes . + DITA Open Toolkit provides .

      @@ -38,10 +38,10 @@

      -

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

      @@ -50,9 +50,7 @@ <b outputclass="badge badge-primary">Preview</b> DITA 2.0 updates

      In addition to the 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 (as of ).

      + the latest draft versions of the DITA 2.0 grammar files from OASIS.

      @@ -60,6 +58,17 @@
      +
      + 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.

      +
      +
      URI dependency tracking

      A new directed graph data structure has been added to track dependencies between resources identified by URI. @@ -69,6 +78,9 @@ 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.

      +

      A generic rose tree data structure has also been added to replace earlier ad hoc implementations. + #4685 +

      @@ -120,6 +132,16 @@
    • 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 @@ -235,6 +257,15 @@ 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 diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index 5b170467..b6296c78 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -35,7 +35,7 @@ - January 22, 2024 + January 25, 2026 From 0a94abb9a4315cc5bf1c3fc8ffc05300580eec41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jeremy=20Jeanne=20=F0=9F=90=9D=E2=98=95=20=F0=9F=90=8D=20?= =?UTF-8?q?=F0=9F=90=A6=E2=80=8D=E2=AC=9B=F0=9F=94=A5?= Date: Thu, 29 Jan 2026 22:10:11 +0100 Subject: [PATCH 34/36] Bump jyjeanne/dita-ot-gradle from 2.3.2 to 2.8.2 (#660) - Update dita-ot-gradle plugin from v2.3.2 to v2.8.2 - Enable Configuration Cache for faster incremental builds Co-authored-by: Jeremy Jeanne Signed-off-by: Jeremy Jeanne --- build.gradle | 32 ++++++++++++-------------------- gradle.properties | 7 ++----- 2 files changed, 14 insertions(+), 25 deletions(-) diff --git a/build.gradle b/build.gradle index 512832c2..4797665a 100644 --- a/build.gradle +++ b/build.gradle @@ -8,7 +8,7 @@ buildscript { } plugins { - id 'io.github.jyjeanne.dita-ot-gradle' version '2.3.2' + id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.2' // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible // Replaced with: inline XsltTransformTask class below } @@ -187,14 +187,12 @@ task autoGenerate(dependsOn: [messages, params, extensionPoints, generatePlatfor task pdf(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build PDF documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide-book.ditamap" output outputDir transtype 'pdf' filter "${projectDirPath}/resources/pdf.ditaval" - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.chapter.layout', 'BASIC') ditaProperties.put('args.gen.task.lbl', 'YES') ditaProperties.put('include.rellinks', '#default external') @@ -205,14 +203,12 @@ task pdf(type: DitaOtTask, dependsOn: autoGenerate) { task html(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build HTML5 documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide.ditamap" output outputDir transtype 'html5' filter "${projectDirPath}/resources/html.ditaval" - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.copycss', 'yes') ditaProperties.put('args.css', 'dita-ot-doc.css') ditaProperties.put('args.csspath', 'css') @@ -227,14 +223,12 @@ task html(type: DitaOtTask, dependsOn: autoGenerate) { task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) { group = 'documentation' description = 'Build HTML Help (.chm) documentation.' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input "${projectDirPath}/userguide.ditamap" output outputDir transtype 'htmlhelp' filter ditavalFile - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.copycss', 'yes') ditaProperties.put('args.css', 'dita-ot-doc.css') ditaProperties.put('args.csspath', 'css') @@ -256,16 +250,13 @@ task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) { } } -task cleanOutput { +task cleanOutput(type: Delete) { group = 'build' description = 'Delete the output directory.' - doLast { - delete outputDir - } + delete file(outputDir) } // Get git commit hash using Gradle 9 compatible Provider API -// Uses providers.exec() instead of deprecated project.exec() def gitCommitHash = providers.exec { commandLine 'git', 'rev-parse', 'HEAD' ignoreExitValue = true @@ -274,13 +265,10 @@ def gitCommitHash = providers.exec { task gitMetadata { group = 'build' description = 'Log git commit metadata.' - // This task just logs the git commit for reference doLast { logger.lifecycle("Git commit: ${gitCommitHash}") } - - // Mark outputs to help with up-to-date checking - outputs.upToDateWhen { false } // Always run since git commit changes frequently + outputs.upToDateWhen { false } } task site(type: DitaOtTask) { @@ -288,26 +276,30 @@ task site(type: DitaOtTask) { description = 'Build website documentation.' dependsOn 'messages', 'params', 'extensionPoints', 'gitMetadata' - // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo. ditaOt file(findProperty('ditaHome') ?: ditaHome) input file("${projectDirPath}/site.ditamap") output getPropertyOrDefault('outputDir', layout.buildDirectory.dir("site").get().asFile.path) filter "${projectDirPath}/resources/site.ditaval" - transtype 'org.dita-ot.html' // Evaluate the noCommitMeta flag at configuration time def includeCommitMeta = !providers.gradleProperty('noCommitMeta').map { Boolean.parseBoolean(it) }.getOrElse(false) - // Use ditaProperties MapProperty directly for v2.3.0 compatibility ditaProperties.put('args.gen.task.lbl', 'YES') ditaProperties.put('args.rellinks', 'noparent') if (includeCommitMeta) { - // Use the git commit hash obtained at configuration time ditaProperties.put('commit', gitCommitHash) } } +// ============================================================================= +// Verification Tasks (v2.8.1 features) +// ============================================================================= + +// ============================================================================= +// Aggregate Tasks +// ============================================================================= + task all(dependsOn: [pdf, html, htmlhelp]) { group = 'documentation' description = 'Build all documentation formats (PDF, HTML, HTMLHelp).' diff --git a/gradle.properties b/gradle.properties index f8f1fc68..f4ad7c61 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,10 +1,7 @@ # Fix Java memory errors with Gradle 5.2 org.gradle.jvmargs = -Xmx1024m -# Gradle 8 features for better performance and caching -# ↓ Not supported by eerohele/dita-ot-gradle ↓ -# org.gradle.configuration-cache=true -# org.gradle.configuration-cache.problems=warn -# ↑ Not supported by eerohele/dita-ot-gradle ↑ +# Gradle 9 features for better performance and caching +org.gradle.configuration-cache=true org.gradle.parallel=true org.gradle.caching=true From 3134be4bd57fbc61d708b83ada9c18533cccd5fe Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 29 Jan 2026 22:22:03 +0100 Subject: [PATCH 35/36] Update & remove comments from build file Signed-off-by: Roger Sheen --- build.gradle | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/build.gradle b/build.gradle index 4797665a..99ccddc7 100644 --- a/build.gradle +++ b/build.gradle @@ -9,8 +9,6 @@ buildscript { plugins { id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.2' - // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible - // Replaced with: inline XsltTransformTask class below } import org.gradle.api.DefaultTask @@ -24,7 +22,7 @@ import javax.xml.transform.stream.StreamSource /** * Gradle 9 compatible XSLT transformation task using Saxon-HE. - * Replaces eerohele/saxon-gradle which is not Configuration Cache compatible. + * Replaces eerohele/saxon-gradle, which is not configuration cache compatible. */ @CacheableTask abstract class XsltTransformTask extends DefaultTask { @@ -77,7 +75,7 @@ abstract class XsltTransformTask extends DefaultTask { } // DSL methods for backward compatibility with saxon-gradle syntax - // Using layout API for Configuration Cache compatibility + // Using layout API for configuration cache compatibility void input(Object path) { inputFile.set(project.layout.projectDirectory.file(path.toString())) } @@ -109,7 +107,7 @@ String ditaHomeSrc = getPropertyOrDefault('ditaHomeSrc', ditaHome) String configDir = "${ditaHomeSrc}/config" String ditavalFile = "${projectDirPath}/platform.ditaval" -// Defer file existence check for Configuration Cache compatibility +// Defer file existence check for configuration cache compatibility Boolean toolkitBuild = providers.provider { file("${projectDirPath}/../lib/dost.jar").exists() }.get() @@ -159,7 +157,7 @@ task generatePlatformFilter { // Use System properties for OS detection (public API) def osName = System.getProperty('os.name').toLowerCase() def platformName = osName.contains('win') ? 'windows' : - osName.contains('mac') ? 'mac' : 'unix' + osName.contains('mac') ? 'mac' : 'unix' // Generate the ditaval file using modern Gradle file operations outputFile.asFile.text = """ @@ -256,7 +254,7 @@ task cleanOutput(type: Delete) { delete file(outputDir) } -// Get git commit hash using Gradle 9 compatible Provider API +// Get Git commit hash using Gradle 9 compatible Provider API def gitCommitHash = providers.exec { commandLine 'git', 'rev-parse', 'HEAD' ignoreExitValue = true @@ -292,14 +290,6 @@ task site(type: DitaOtTask) { } } -// ============================================================================= -// Verification Tasks (v2.8.1 features) -// ============================================================================= - -// ============================================================================= -// Aggregate Tasks -// ============================================================================= - task all(dependsOn: [pdf, html, htmlhelp]) { group = 'documentation' description = 'Build all documentation formats (PDF, HTML, HTMLHelp).' From 3f69e5244f9ad3bb7803f9aec1404f38f3569342 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Thu, 29 Jan 2026 22:30:03 +0100 Subject: [PATCH 36/36] Move URI dependency tracking info to enhancements Signed-off-by: Roger Sheen --- release-notes/index.dita | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index ff0756b1..d5a06ba0 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -69,20 +69,6 @@ automated build pipelines that need to parse DITA-OT output programmatically.

      • -
      - URI dependency tracking -

      A new directed graph data structure has been added to track dependencies between resources identified by URI. - #4716 -

      -

      This internal infrastructure improvement provides 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.

      -

      A generic rose tree data structure has also been added to replace earlier ad hoc implementations. - #4685 -

      -
      -
      Enhancements and changes @@ -188,6 +174,25 @@ #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.

      +
@@ -283,7 +288,7 @@
  • Jarno Elovirta
  • Dávid Bertalan
  • Roger Sheen
    • -
  • Robert D Anderson
    • +
  • Robert D. Anderson
  • Chris Papademetrious
  • Joshua Johnson
  • Julien Lacour