Context-Sensitive HTML Help Using the The DITA Open Toolkit

This topic provides a brief introduction to the HTML Help transform in the DITA Open Toolkit.

We would be remiss not to call attention to the original HTML Help transform that has been bundled with the DITA Open Toolkit for several years.


Output from the DITA Open Toolkit HTML Help plug-in serves as input to the Microsoft HTML Help Compiler. If you choose to build your DITA sources on the same Windows system on which you have installed a copy of the Microsoft HTML Help Software Development Kit, you will be able to generate a ready-to-deploy MS HTML Help .chm library from your DITA-OT ant script. Otherwise, you an copy output from the DITA Open Toolkit HTML Help transform on your DITA-OT build system to some other Windows system on which the HTML Help SDK has been installed.

Setup and configuration

Once you have installed and configured the DITA Open Toolkit, you have the HTML Help transform installed by default and ready to use. See the DITA Open Toolkit User's Guide for detailed information about working with transforms and about specifying the HTML Help transform specifically as a processing target (dita2htmlhelp).

To download the latest Microsoft HTML Help 1.4 SDK, go to the following MSDN web site. It is a free download.

Note: If you run the test build script that is bundled with the Open Toolkit, sample_all.xml, you can verify that the HTML Help transform is installed and configured correctly by looking in the ant/out/samples/htmlhelp subdirectory.


To generate ready-to-deploy .chm libraries from most any DITA source collection, you do not really have to customize or rework your DITA source files.

DITA source MS HTML Help output

DITA map entries

Contents tab entries

index entries

Index tab entries

running text

full-text search index


Truth be known, there are also limitations to both this DITA-OT transform and to the MS HTML Help run-time environment. Factor these into your planning.


The .chm library produced by the combination of the DITA-OT HTML Help transform and the MS HTML Help compiler is very functional.

Here's what output from the DITA-OT test collection looks like.

Figure 1. Garage Tasks Contents Tab in HTML Help

Figure 2. Garage Tasks Search Tab in HTML Help

Note: The DITA-OT test collection source files contain no index entries, so no index entries are generated in MS HTML Help.


If you have requirements to deploy a general-purpose Help collection to Windows customers without context-sensitive integration, consider using the DITA-OT HTML Help transform. It is functional, reliable and fast. Once all your content in is .chm format, you can convert it to other distribution formats with second-tier conversion tools such as chm2web. If you have requirements to integrate .chm output with Windows applications as Context-sensitive Help, you'll need to invest some time managing maps and alias files outside the DITA environment and then integrating them with .chm output using WinAnt or other custom processing environments.

Stan Doherty


OASIS DITA Technical Committee

OASIS DITA Help Subcommittee