This topic provides an overview of the DITA-OT plug-ins named tocjs and tocjsbis.

The tocjs DITA-OT plug-in and its more recent enhancement named tocjsbis generate a JavaScript-based table of contents page for any DITA topics that you reference in your .ditamap file.


These plug-ins are very popular in the DITA community; we even use them on the DITA Technical Committee for our DITA 1.2 specifications.

Figure 1. OASIS DITA Technical Specification in tocjs

If you are generating HTML output of any sort from your DITA sources, you should test one or both of these plug-ins. I use tocjsbis in my context-sensitive Help builds where I work. To the extent that the tree control in tocjs and tocjsbis are based on the Yahoo tree control library, you can customize the way that the final TOC tree displays and behaves in your Help system. They can be tricky, but customizations work.

Setup and configuration

The tocjs and tocjsbis plug-ins are free downloads from the Yahoo DITA-OT site.

Figure 2. tocjs Download

After you have unzipped these archives to a local directory, you can browse the documentation to get a feel for what tocjs offers and how you can install it in your DITA-OT directory.

Figure 3. tocjs Installation

The pre-built documentation for tocjs lives in the /docs subdirectory.

Figure 4. tocjs Documentation

Installing tocjs or tocjsbis is very straightforward.

  1. Copy the un-achived tocjs or tocjsbis 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. Change directory into the demo/tocjs or demo/tocjsbis subdirectory and enter the following command to build the sample DITA topics.
    ant -f demo/tocjs/buildsample.xml sample2tocjs
  5. Load the newly generated demo\tocjs\out\sample\frameset.html file in your browser.

If you are considering customizations to tocjs or tocjsbis, consult the documentation for the Yahoo UI tree control at the following URL.

Figure 5. Yahoo UI Library

That is about all that is involved with installing and configuring tocjs and tocjsbis.


These plug-ins piggy-back whatever investment you have already made in authoring your DITA topics and map files. Beyond setting up a new ant script for tocjs or tocjsbis, there is nothing additional required.


The tocjs and tocjs plug-ins present few integration problems or opportunities, especially as regards managing context sensitivity between Help output and the calling software application. Many DITA Help writers customize the frameset.html file that ships with the tocjs plug-in to personalize or brand the final product. Here's what Shawn McKenzie does with tocjs on his Sophos corporate website.

Figure 6. Sample tocjs Documentation

Wrapping other navigational devices around the tocjs output is not difficult. I add the conventional tabs for tri-pane Help systems.

Figure 7. Integrated tocjsbis

In terms of translation, note that all the text strings associated with entries in the TOC tree are stored in one file named toctree.js. These files can be localized, for sure, but they are not very friendly. To make life easier on our sisters and brothers in L10N, you can post-edit this toctree.js file to swap JavaScript resource strings for literal strings.


Here again is a link to a live demo of tocjs running at Sophos.


If you are comfortable customizing XHTML output to build an HTML-based help system, you should consider tocjs and tocjsbis. They are sufficiently lightweight to work in Help systems or web-based portals.

Stan Doherty


OASIS DITA Technical Committee

OASIS DITA Help Subcommittee