diff --git a/build.gradle b/build.gradle
index 729ad205e..99ccddc7b 100644
--- a/build.gradle
+++ b/build.gradle
@@ -3,14 +3,12 @@ buildscript {
mavenCentral()
}
dependencies {
- classpath 'net.sf.saxon:Saxon-HE:10.6'
+ classpath 'net.sf.saxon:Saxon-HE:12.9'
}
}
plugins {
- id 'io.github.jyjeanne.dita-ot-gradle' version '2.3.2'
- // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible
- // Replaced with: inline XsltTransformTask class below
+ id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.2'
}
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 = """
@@ -187,14 +185,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 +201,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 +221,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 +248,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()
+// Get Git commit hash using Gradle 9 compatible Provider API
def gitCommitHash = providers.exec {
commandLine 'git', 'rev-parse', 'HEAD'
ignoreExitValue = true
@@ -274,13 +263,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,22 +274,18 @@ 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)
}
}
diff --git a/gradle.properties b/gradle.properties
index f8f1fc682..f4ad7c61b 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
diff --git a/parameters/ant-parameters-details.dita b/parameters/ant-parameters-details.dita
index 1badd09de..ebce4a586 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.
@@ -713,15 +711,21 @@
.
-
+ outputFile.base
+
+ deprecated features
+ outputFile.baseBy 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.
+
@@ -738,18 +742,29 @@
formatter
-
+
+
publish.required.cleanupdeprecated features
+ publish.required.cleanup
+ parameters
publish.required.cleanup
-
- 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.
+ 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
+ args.draft instead.
diff --git a/parameters/dita-command-arguments.dita b/parameters/dita-command-arguments.dita
index 4fa009a09..a6769d72e 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.
DITA-OT 4.1 added support for additional DITA 2.0 features.
@@ -186,8 +196,10 @@
- DITA-OT 4.3
-
DITA-OT 4.3 adds support for additional DITA 2.0 features.
+ 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
on the DITA 2.0 video element to ensure that videos are scaled correctly.
@@ -199,6 +211,86 @@
+
+ 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
+
+
+
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
+
+
+
+ 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 9750592d7..d5a06ba0f 100644
--- a/release-notes/index.dita
+++ b/release-notes/index.dita
@@ -1,15 +1,14 @@
-
+DITA Open Toolkit <keyword keyref="release"/> Release NotesRelease Notes
- DITA Open Toolkit is a maintenance release that fixes issues
- reported in DITA-OT , which includes .
+ DITA Open Toolkit provides .
@@ -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 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 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 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 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>-->
@@ -284,180 +38,160 @@
-
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.
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.
+
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.
-
- 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
-
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 ).
-
-
+ 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.
+
+
+ JSON logging
+
A new --logger=json option enables structured JSON log output for easier log processing
+ and analysis.
+ #4581
+
+
When logging to standard output, each line is a separate JSON object. When logging to a file, the output is
+ formatted as a JSON array. This structured format simplifies integration with log aggregation tools and
+ automated build pipelines that need to parse DITA-OT output programmatically.
+
+
Enhancements and changes
DITA Open Toolkit Release 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
+
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
-
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
+
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 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
+
A new --stacktrace command-line option has been added to print the full Java
+ stack trace when an error occurs. This option is useful for debugging and troubleshooting, and can help
+ developers and support teams diagnose issues more quickly. By default, stack traces are no longer included
+ in verbose logging output to reduce noise for end users.
+ #4579
+
+
The --deliverable option can now be specified multiple times on the command
+ line to publish several deliverables from a project file in a single build. This allows you to select
+ specific deliverables without publishing all deliverables defined in the project.
+ #4583
+
+
In HTML5 transformations, note bodies are rendered as div elements with
+ display: inline applied to allow single-line note rendering for inline note content. A CSS
+ comment has been added to the default stylesheets to explain this styling choice.
+ #4629,
+ #4631
+
+
The keyref parser has been refactored to improve code quality and prepare for future feature
+ additions.
+ #4637
+
+
Topic ID values are now cached during keyref resolution as a performance optimization. This
+ cache is used for key definitions that point to a file without a topic ID in the fragment identifier. Key
+ definitions that include a topic ID (such as href="topic.dita#id") are not affected.
+ #4638
Several bundled dependencies have been upgraded to the latest versions:
-
2.10 (including the and
- libraries)
- #4519,
- #4565
+
Gradle has been updated to version 9.3.
+ #4727,
+ #4740
+
+
JUnit has been updated to version 6.0.2.
+ #4740
+
+
Logback core has been updated to 1.5.19 to address a security vulnerability.
+ #4743
+
+
Saxon has been updated to version 12.9, which includes minor bug fixes.
+ #4712,
+ #4739
+
+
XSpec has been upgraded to version 3.2.2, which improves XSLT test capabilities and now reports all
+ failing tests in a file instead of just the first one.
+ #4665
+
+
+
+
Various internal code improvements have been made for better code quality, test coverage, and
+ maintainability:
+
+
Test class names now consistently use a Test suffix
+ #4657
+
+
File stream creation now uses the modern Files API
+ #4663
+
+
Unit tests have been added for coderef processing
+ #4664
+
+
Gradle build scripts have been refactored
+ #4666
+
+
Debug output now includes task descriptions for XHTML builds
+ #4672
+
+
Integration test result reporting has been improved
+ #4673,
+ #4676,
+ #4677,
+ #4678,
+ #4679
+
+
Preprocessing modules have been refactored for better readability
+ #4680,
+ #4684
+
+
Test method naming conventions have been standardized
+ #4690
+
+
General code refactoring for improved quality and performance
+ #4718,
+ #4724
+
+
+
A new directed graph data structure has been added to track dependencies between resources identified
+ by URI. A generic rose tree data structure has also been added to replace earlier ad hoc
+ implementations.
+ #4685,
+ #4716
+
These internal infrastructure improvements provide a foundation for more sophisticated link
+ and dependency tracking between files and topics. The new Graph and
+ UriGraph classes enable DITA-OT to model and traverse relationships between
+ resources, which will support future enhancements to content processing and validation.
@@ -468,19 +202,78 @@
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 of DITA-OT threw a NullPointerException when using the
+ --root-chunk-override option with the DITA 2.0 combine value. Chunk
+ processing has been updated to handle this case correctly.
+ #4036
+
+
In previous releases, DITAVAL passthrough actions in HTML5 transformations were
+ not applied to top-level (root) topic elements, even though they worked correctly
+ for nested topics. The root-topic template has been updated to generate the expected
+ data-attname passthrough attributes on the HTML5 body element.
+ #4464,
+ #4639
+
+
Using the --root-chunk-override=combine option with DITA 2.0 content that
+ contained xref elements caused a NullPointerException during link
+ rewriting. Chunk processing has been updated to handle cross-references correctly.
+ #4511
+
+
Using the --root-chunk-override=combine option with DITA 2.0 content that
+ contained tables caused a SAXParseException due to unbound namespace prefixes. The
+ namespace prefix tracking has been fixed to ensure that internal attributes are correctly handled when links
+ are inserted during chunk processing.
+ #4513,
+ #4738
+
+
The Gradle build configuration has been updated to correctly locate the Node.js executable path
+ on Windows systems.
+ #4688
+
+
When using a DITA 2.0 map schema, the navtitle element within
+ topicref was ignored, causing navigation entries to be suppressed or flattened in
+ HTML5 output. The transformation now matches both the DITA 1.3 and DITA 2.0 class values for
+ navtitle.
+ #4695
+
+
Combine chunking for the root map in DITA 2.0 has been fixed.
+ #4698
+
+
The attribute stack in the force-unique filter and merge-map parser modules was not being
+ correctly maintained, which could cause attributes to be incorrectly applied during processing. The stack
+ management has been fixed to ensure attributes are properly tracked.
+ #4705,
+ #4706
+
+
In XHTML and Eclipse Help output, trademark symbols in related links caused processing to fail
+ because the key() function was called on an intermediate tree without a document node. This
+ fix ports an earlier HTML5 correction to the XHTML transformation, passing the original root node as a
+ tunnel parameter for key lookups.
+ #4686,
+ #4717
-
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
+
From the initial public release of DITA-OT, section titles in HTML output have been styled with
+ a CSS color property that set text color to black. This creates problems in inverted color
+ schemes like dark mode themes, where section titles did not have sufficient contrast with the background. No
+ other heading levels specify text color, so this version removes the color property to allow themes to
+ modify section title color along with other headings and text.
+ #4731
+
+
The PDF2 parameter outputFile.base has been marked as deprecated. (Use
+ args.output.base instead.)
+ #4732,
+ dita-ot/docs#648
+
+
A stale reference to the deprecated args.logdir parameter has been removed
+ from test code. This parameter was deprecated in DITA-OT 2.5 and removed in 3.4.
+ #4733
@@ -489,21 +282,22 @@
Contributors
DITA Open Toolkit Release includes
by the following people:
-
+
NOTE: This lists contributions to the core toolkit, not docs.
Jarno Elovirta
-
Julien Lacour
-
Robert D Anderson
+
Dávid Bertalan
Roger Sheen
-
Andrei Pomacu
+
Robert D. Anderson
Chris Papademetrious
-
Jason Fox
-
+
Joshua Johnson
+
Julien Lacour
+
Guillaume Delory
+
Gregor Latuske
For the complete list of changes since the previous release, see the
changelog on GitHub.
@@ -511,21 +305,29 @@
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.
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
milestone in the documentation repository.
@@ -535,12 +337,15 @@
Roger Sheen
Jarno Elovirta
+
Darrenn Jackson
+
Dávid Bertalan
+
Jeremy Jeanne
Lief Erickson
-
Stefan Weil
+
Stefan Jung
For the complete list of documentation changes since the previous release, see the
changelog.
diff --git a/release-notes/rel4.3.dita b/release-notes/rel4.3.dita
new file mode 100644
index 000000000..9a64f8667
--- /dev/null
+++ b/release-notes/rel4.3.dita
@@ -0,0 +1,550 @@
+
+
+
+
+ DITA Open Toolkit 4.3 Release Notes
+
+ Release Notes
+
+
+
+ DITA Open Toolkit 4.3.5 is a maintenance release that fixes issues
+ reported in DITA-OT 4.3, which includes .
+
+
+
+
+
+ Requirements: Java 17
+
+
+ Add info on new minimum Java version or any other requirements that have changed
+ since previous release.
+
+
+
+
+
+
+
+ DITA-OT 4.3.5
+ <ph outputclass="small text-muted">released October 21, 2025</ph>
+
+
+
+
DITA Open Toolkit 4.3.5 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 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 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 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 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 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
+ themes.
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
+
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 4.3 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 4.3 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 4.3 includes
+ by the following people:
+
+ NOTE: This lists contributions to the core toolkit, not docs.
+
+
Jarno Elovirta
+
Julien Lacour
+
Robert D Anderson
+
Roger Sheen
+
Andrei Pomacu
+
Chris Papademetrious
+
Jason Fox
+
+
+
For the complete list of changes since the previous release, see the
+ changelog on GitHub.
+
+
+
+ Documentation updates
+
The documentation for DITA Open Toolkit Release 4.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 4.3 navigation changes
+
+
+
+
For additional information on documentation issues resolved in DITA Open Toolkit Release , see the
+ 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.
+
+
Roger Sheen
+
Jarno Elovirta
+
Lief Erickson
+
Stefan Weil
+
+
For the complete list of documentation changes since the previous release, see the
+ changelog.
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.
diff --git a/topics/migrating-to-4.4.dita b/topics/migrating-to-4.4.dita
new file mode 100644
index 000000000..97973ce6b
--- /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 5e40af205..bba817178 100644
--- a/topics/migration.ditamap
+++ b/topics/migration.ditamap
@@ -4,6 +4,7 @@