DITA Open Toolkit 3.0.1 Release Notes

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

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

Maintenance Release 3.0.1

DITA Open Toolkit Release 3.0.1 includes the following bug fixes.

  • Microsoft Compiled HTML Help requires a Windows codepage rather than UTF-8, so many characters are converted to HTML entities to ensure they are preserved during the codepage conversion. In earlier versions of DITA-OT, these entities were not rendered correctly in index terms or in topic titles on the Contents tab of the .chm file. This is now fixed; characters that exist in the target codepage are not converted to entities, so they will appear properly in the compiled help file. #1151, #1271, #2852
  • When unordered lists nest greater than 4 levels, PDF processing generates a warning about a missing variable, and deeply nested lists use text such as Unordered List bullet 5 instead of a bullet character. Characters for levels 1 through 4 now repeat in deeply nested lists. #2824, #2853
  • Map-first processing in 3.0 uses generated file names in the temp directory for HTML Help, but this breaks any existing context-sensitive help projects that call topics directly by file name rather than by aliased constants (topic IDs) or help context numbers. Topics in the compiled help file are now restored to their original names to support external applications that to link to topics within a CHM by file name. #2830
  • Simplified common variable definitions in 3.0 could not be overridden using the traditional customization approach; the override process now checks for common variables to ensure those in the configuration directory are used. #2833, #2838
  • Generating Markdown output with DITA-OT 3.0 failed with references to a missing stylesheet. The Lightweight DITA plug-in has been updated to the latest version (2.0.1), which corrects the plug-in directory path in the stylesheet reference, so Markdown output is now generated as expected. #2836, #2846
  • In 3.0, HTML Help project files would not compile to CHM files because a property definition was not properly initialized. This has been fixed and CHM files are generated using the original map name. #2851
  • In 3.0, the args.output.base property to name output files does not work properly for HTML Help. The property is now used to produce a CHM file with the correct name and contents. #2854
  • In 3.0, content references to warehouse topics that contain unresolved cross-references would cause PDF builds to fail, even if the invalid reference was not explicitly included in the content reference. DITA-OT now checks to make sure such files exist and only parses them if available. #2856
  • The documentation includes minor changes with corrections and improvements to existing topics.

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


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, #2822
  • 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.