DITA Open Toolkit 3.0 Release Notes

DITA Open Toolkit 3.0 is a feature release that provides new features and enhancements, including new Markdown input and output formats, normalized DITA output, and preview support for alternative authoring formats proposed for Lightweight DITA. The map-first preprocessing approach provides a modern alternative to the default preprocess operation.

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


DITA Open Toolkit Release 3.0 requires the Java Runtime Environment (JRE) version 8 or later.

Release Highlights

DITA-OT 3.0 includes new Markdown input and output formats, normalized DITA output, and preview support for alternative authoring formats proposed for Lightweight DITA. The map-first preprocessing approach provides a modern alternative to the default preprocess operation.

Markdown support

The Markdown implementation previously provided by the external dita-ot-markdown plug-in has been updated to support additional edge cases and bundled into the DITA-OT 3.0 release.

Markdown topics can be added to DITA publications by setting the @format attribute to markdown so the toolkit will recognize the source file as Markdown and convert it to DITA:

  <topicref href="markdown-dita-topic.md" format="markdown"/>

Along with Markdown input, DITA-OT now provides three new output formats to convert DITA content to Markdown, including the original markdown syntax, markdown_github for GitHub-Flavored Markdown, and markdown_gitbook for publishing via GitBook.

Markdown output can be generated by passing one of these keywords to the dita command with the --format option:

dita --input=userguide.ditamap --format=markdown

The new output formats can be used to feed DITA content into Markdown-based publishing systems or other workflows that lack the ability to process DITA XML.

Note: The Markdown support is based on CommonMark, a strongly defined, highly compatible specification of Markdown and implemented via the flexmark-java parser.

Preview support for Lightweight DITA

The new org.lwdita plug-in replaces the earlier dita-ot-markdown plug-in and provides preview support for the MDITA and HDITA authoring formats proposed for Lightweight DITA.

The @format attribute can be set to mdita to apply LwDITA-specific processing to Markdown topics:

  <topicref href="mdita-topic.md" format="mdita"/>

In this case, the first paragraph in the topic will be treated as a short description, for example, and additional metadata can be specified for the topic via a YAML front matter block.

Attention: Since Lightweight DITA has not yet been released as a formal specification, the implementation for MDITA and HDITA authoring formats is subject to change. Future versions of DITA Open Toolkit will be updated as LwDITA proposals evolve.

Normalized DITA output

The new dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of the DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.

In comparison to the source DITA files, the normalized DITA files are modified in the following ways:

  • References from one DITA map to another are resolved
  • Map-based links, such as those generated by map hierarchy and relationship tables, are added to the topics.
  • Link text is resolved.
  • Map attributes that cascade are made explicit on child elements.
  • Map metadata such as index entries and copyrights are pushed into topics.
  • Topic metadata such as navigation titles, link text and short descriptions are pulled from topics into the map.
  • XML comments are removed.

Normalized output can be used during plug-in development to troubleshoot the results of preprocessing routines, or in situations where post-processing of DITA content is required, but the downstream systems are limited in their ability to resolve DITA references.

Tip: The dita transformation can also be used to convert Markdown topics or the alternative input formats supported by the org.lwdita plug-in to standard DITA XML.

Map-first preprocessing

DITA-OT 3.0 provides a map-first preprocessing option as an alternative to the default preprocess operation. The method, which was introduced in DITA-OT 2.5 as an experimental feature, has been improved and is ready for use in many production scenarios. Map-first-preprocessing provides the same functionality as the default preprocess, but takes a different approach.

Whereas the default preprocessing routine handles both maps and topics at the same time, often switching back and forth between map operations and topic operations, the map-first approach only begins processing topics after nearly all map processing is complete. This simplifies the processing logic and creates cleaner module responsibilities, which makes it easier to process only those topics that are actually referenced after filtering, for example, or to only process the map to validate the map structure.

Note: The map-first preprocessing option is enabled by default in DITA-OT 3.0 for PDF, HTML Help, and Java Help. These three formats were chosen because they all generate a compiled result file, so temporarily hashed file names should all be invisible to the build. After further testing and feedback, the new option will most likely become the default for other output formats in future versions. Because the DITA-OT development team cannot have access to all varieties of DITA, all edge cases, or even all the ways DITA-OT itself is extended, the switch to default map-first preprocessing for other output formats will be smoother for everyone if more people can test and provide feedback.

Resolved issues

In addition to the highlights mentioned above, DITA Open Toolkit Release 3.0 includes the following changes.


DITA Open Toolkit Release 3.0 includes the following new features:

  • A new property named args.output.base can be used control the name of the output file for transform types that produce a single output file. The value of the property is the base file name of the output file, without file extension. The file extension is defined by the transform type. #1200
  • Move from custom logging to SLF4J and Logback #1471
  • HTML Help project files are now generated in a temporary directory, so that only the compiled CHM file is returned. #1551
  • Add support for subject schemes in map-first preprocess #2626
  • Extension point for Ant import task #2766
  • Add Markdown plugin to distribution package #2774
  • Add normalization plugin to distribution package #2775

Enhancements and changes

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

  • Obsolete or unmaintained plugins have been moved to their own repositories. The following plugins have been moved: Docbook, Eclipse Content, Eclipse map specialization, RTF, ODT, and support for pre-OASIS DITA document types. #2121
  • Use XMLUnit 2 #2232, #2723
  • Generated link groups in XHTML and HTML5 now use list markup rather than <div>, as required to comply with WCAG 2.0 accessibility guidelines. #2447
  • Upgrade Gradle to 3.5 #2713
  • When building PDF from files that do not use .dita or .ditamap extensions, the input file extension (such as .xml) is no longer included in the generated PDF file name. #2718
  • Upgrade to Saxon-HE 9.8 #2721, #2727
  • Upgrade to FOP 2.2 #2736
  • When merging submaps for processing, preserve titles and metadata from the referenced submap so that they may be used in later processing stages. #2739
  • Add flagging information from DITAVAL during the same step that handles DITAVAL filtering. #2748
  • Allow for plugin param type 'url' #2755
  • Use map-first preprocessing in PDF and HTML Help transformation types #2763
  • Move or rename Java classes #2765
  • Make it easier for PDF plugins or overrides to customize how processing handles the DITA @outputclass attribute, such as by mapping it to corresponding XSL:FO attributes. #2770
  • Topics exploded by chunk should be written to the topic folder #2780
  • Move configuration files to a dedicated config/ directory, which ensures that configuration files and generated files like messages.xml will not be bundled into the compiled dost.jar #2781, #2783
  • Allow any attribute to be used for profiling #2784
  • Support language-independent variable files. For variables common to all (or nearly all) languages, this means we no longer need to maintain an individual copy of the variable for every language. Plugins may also now define variables that are used by all languages. #2789
  • Use doubled dashes in messages #2808
  • Refactor HTML5 <simpletable> accessibility to use more modern attributes to associate table entries with header cells. #2811, #2448


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

  • Images referenced in conref source copied to output #1364
  • Email links without a scope or format previously generated a Null Pointer Exception. The mailto: syntax is now recognized as an email link and will not be read as a file reference. #2654
  • The wrong language code was previously set when documents set @xml:lang to the value zh-Hans #2742
  • According to the DITA 1.3 specification, when key definitions refer to images, text that would otherwise become link text should be placed in the images @alt element as alternative text. Previously the text was placed directly into the <image>, which was not valid and ignored by later processing. #2752, #2814
  • In earlier releases, when a <table> element included too many entries in a row, FOP would crash during PDF processing. The extra entries are now ignored with an error message. #2782
  • A Java method for generating relative paths failed on Windows when comparing two paths from different drives. The method has been fixed so that it does not try to construct a relative path between drives. #2797
  • In HTML5, a DITA <stepsction> that contained paragraphs resulted in HTML5 <p> elements that contained <p>. The <stepsection> now generates a <div> to ensure valid HTML5 output regardless of what it contains. #2807
  • An updated errata has been approved for DITA 1.3 that removes default values for @rowheader on <colspec>. The relevant grammar file modules from OASIS have been updated to include this errata. #2810


DITA Open Toolkit Release 3.0 includes code contributions by the following people:

  1. Jarno Elovirta
  2. Robert D. Anderson
  3. Roger Sheen
  4. Alexey Mironov

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

Documentation updates

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

  • Revised top-level documentation structure #121
  • New topics on Markdown plug-in #150
  • New topic on Lightweight DITA #151
  • New topic on normalization plug-in #152

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

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

  1. Roger Sheen
  2. Robert D. Anderson
  3. Jarno Elovirta
  4. Shane Taylor
  5. Misti Pinter
  6. Garrett Guillotte
  7. Lionel Moizeau
  8. Stefan Eike

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