# DITA Open Toolkit 4.3 Release Notes

DITA Open Toolkit 4.3.1 is a maintenance release that fixes issues reported in DITA-OT 4.3, which 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.

DITA-OT releases follow semantic versioning guidelines. Version numbers use the major.minor.patch syntax, where major versions may include incompatible API changes, minor versions add functionality in a backwards-compatible manner and patch versions are maintenance releases that include backwards-compatible bug fixes.

Tip:
Download the dita-ot-4.3.1.zip package from the project website at dita-ot.org/download.

## Requirements: Java 17

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

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

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

## DITA-OT 4.3.1

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 4.3 released February 15, 2025

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.

### Preview 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 dita init --list
- To add files from a template to the current directory, run dita init template

The folder hierarchy in the template will be copied to the current working directory by default. To write the files to a different location, add the --output option and specify the desired path. The directory will be created if it doesn’t exist. If any of the template files are already present, an error will appear.

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

    dita -i sample.ditamap -f html5 -f pdf

The result will be the same as if you had issued separate commands for each format:

    dita --input=sample.ditamap --format=html5
    dita --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 5.9, 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 HTML5-compliant syntax highlighting with libraries like Prism. #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 Markdown DITA syntax, 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

### Bookmap support in PDF themes

The PDF theme plug-in `com.elovirta.pdf` has been updated to version 0.8 for better bookmap support. #111 You can now style the following bookmap elements in a YAML or JSON theme without building a custom PDF plug-in:

- `<part>`
- `<chapter>`
- `<appendix>`
- `<index>`

Table of contents (ToC) styles have moved to the root `style` key. ToC styling has also been extended for better bookmap support, so you can now specify styles for each level with dedicated keys such as `style-toc-part`, `style-toc-chapter`, etc.

Parts and chapters now also support their own local contents listings, which you can enable by setting the corresponding layout key, for example `chapter-layout: MINITOC`. You can then define styling for each level via keys like `style-part-toc-chapter`, or `style-chapter-toc-1`.

A new `default` theme provides basic styling such as font settings, indentation, and title numbering for a range of commonly used elements. This theme is not intended for publishing as is, but can serve as a foundation for custom themes, and reduce the number of elements you need to style yourself. To use the default theme as the baseline for your own custom theme, add `extends: default` to your theme file. #112, #114

### Preview DITA 2.0 updates

In addition to the DITA 2.0 preview support 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 January 22, 2024).

- HTML5 processing now supports the `@height` and `@width` attributes on the DITA 2.0 `<video>` element to ensure that videos are scaled correctly. #4570
- HTML5 and PDF processing has been updated to support the new DITA 2.0 emphasis domain elements: `<em>` for emphasis and `<strong>` for strong emphasis. #4571

DITA documents that reference the draft grammar files can be parsed, and where features overlap with DITA 1.3, those features will work as expected.

Note:
Other new or revised features proposed for DITA 2.0 are not yet supported. Additional features will be implemented in future versions of DITA-OT as the specification evolves.

### 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:
  - Apache™ FOP 2.10 (including the Apache XML Graphics and Batik 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 code contributions by the following people:

1. Jarno Elovirta
2. Julien Lacour
3. Robert D Anderson
4. Roger Sheen
5. Andrei Pomacu
6. Chris Papademetrious
7. 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 Figure 1 shows the previous structure on the left, and the new locations on the right.

Figure 1. DITA-OT 4.3 navigation changes
The legacy Ant samples and garage sample files have been removed from the docsrc/samples subfolder of the installation directory. If your workflow relies on these files, you can restore them to the original location with the new init subcommand:

    dita init samples path/to/dita-ot-dir/docsrc/samples

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

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

1. Roger Sheen
2. Jarno Elovirta
3. Lief Erickson
4. Stefan Weil

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