HTMLSearch Plug-in

This topic introduces the DITA plug-in named HTMLSearch.

The HTMLSearch plug-in for the DITA Open Toolkit builds a keyword-based search index and a default frame-based user interface for any collection of DITA topics referenced by a DITA map file.


Nadege Quaine (, the contributor of the tocjsbis plug-in, has also contributed this plug-in. As of this writing, the most current version of the plug-in is dated April 8, 2008 and is distributed as

The HTMLSearch plug-in first runs the XHTML transform that comes with the DITA-OT and then runs an indexing application against those XHTML output files. HTMLSearch deposits the keyword index and the supporting JavaScript worker libraries in a subdirectory named search.

Figure 1. HTMLSearch JavaScript Output

Each of these JavaScript index files correlates discovered keywords to one or more numerals representing particular XHTML output topics.

Figure 2. HTMLSearch JavaScript Search Array

The keyword "ant," for example, appears in three XHTML topics. These target topics are referenced numerically (1, 2, 5) and indexed separately in the file search\htmlFileList.js.

Figure 3. HTMLSearch Keyword-to-Targte-File Array

When you open the default HTMLSearch web page (frameset.html) in the output directory, it opens three frames containing a keyword input box, some default information about the plug-in, and a splash screen.

Figure 4. HTMLSearch UI

Results from a keyword search are displayed in the right-hand pane.

Figure 5. HTMLSearch UI

Figure 6. HTMLSearch UI

Clicking a hyperlink in the results list displays the target topic containing the keyword in the same right-hand pane.

The plug-in works fine in all versions of the DITA-OT because it is really interacting with XHTML output from the DITA-OT, not Open Toolkit resources per se. Beyond minor variations in the way the HTML displays in different browsers, HTMLSearch output works reliably in all modern browsers.

Setup and configuration

The HTMLSearch plug-in is a free download from the Yahoo DITA-OT site.

After you have unzipped this archive to a local directory, you can browse the README.txt file to get a feel for what HTMLSearch offers and how you can install it in your DITA-OT demo directory.

Figure 7. HTMLSearch Plug-in Installation

Installing the plug-in presents no surprises.

  1. Copy the un-archived htmlsearch subdirectory into the demo subdirectory of your DITA Open Toolkit directory.
  2. Open a shell command window from your DITA-OT directory.
  3. Enter the following command to integrate the new plug-in or plug-ins with your current DITA-OT environment.
    ant -f integrator.xml
  4. From the DITA-OT root directory, enter the following command to build the sample DITA topics.
    ant -f demo/htmlsearch/buildsample.xml xhtml2search
  5. Load the newly generated demo\htmlsearch\out\frameset.html file in your browser.

That is about all that is involved with installing and configuring the plug-in.


There are no DITA source-level authoring considerations for this plug-in; it works on XHTML output topics generated by the DITA-OT XHTML transform.


Integrating output from the HTMLSearch plug-in with tocjsbis output or with your local favorite HTML implementation is possible, but challenging. If you have some experience modifying (or hacking) HTML frames and JavaScript code, have at it. Otherwise, you might consider continuing to use HTMLSearch output as a stand-alone complement to your other output transformations.

Consider the following tips when planning your customization effort.

These are the most visible variables that you'll need to consider when customizing HTMLSearch output for your own help implementation.


Although the customization process can sound scary, it does produce some very nice results. Here is a prototype Help implementation for my current company. The goal here is to integrate the output from HTMLSearch with output from tocjsbis in a garden-variety three-tab, multi-frame HTML shell. Initially, the search UI is linked to a Search tab.

Figure 8. Integrated HTMLSearch

When the customer clicks the Search tab, a re-implementation of the HTMLSearch UI is displayed.

Figure 9. Integrated HTMLSearch

Search results appear in a lower frame in the left-hand navigation frame.

Figure 10. Integrated HTMLSearch

When the customer clicks one of the hyperlinks in the results list, that topic is displayed in the right-hand frame.

Figure 11. Integrated HTMLSearch


Customizing HTMLSearch to integrate it with tocjsbis or other XHTML output transformations from the Open Toolkit goes a long way toward making DITA-generated Help more usable and familiar to contemporary audiences.

Stan Doherty


OASIS DITA Technical Committee

OASIS DITA Help Subcommittee