How to substitute your custom CSS when using DITA Open Toolkit transforms

Version 1
    Share This:

    When you want to use the DITA Open  Toolkit transforms but you want to use your own CSS, here's how to substitute  your CSS for HTML Help (CHM).

    Here's how I was able to substitute my own CSS (Cascading Style Sheet) file  when using the DITA transforms to make compiled help files (CHM). I did several  Google and Yahoo Group searches in the dita-users group for phrases like "switch  css chm" and "substitute css chm" but didn't find quite what I was looking for,  so I decided to try a few things and write it up. After figuring it out, I did  find the topic covered for XHTML in the DITA Open ToolKit User Guide and it contains all the information  I needed to make it work for CHM. I just needed to leave that "CHM" keyword out  of the search phrases I was using! Go figure.


    Here's an overview of what I did to get it to work in my environment on  Windows. This process should work for other platforms as well.

    First, create a CSS file that contains the modifications you want for styling  your output. I basically took the generated CSS commonltr.css and made  modifications to that file, then saved it as a new CSS file called  bmc_dita_chm.css.


    Second, make sure you can build using Ant and create your own Ant script  using the ant/template_htmlhelp.xml file provided with the DITA Open  Toolkit. Basically, you take the ant/template_htmlhelp.xml file and  substitute your project names in the file, then save the file with a new name  such as build_htmlhelp.xml. Then you go to a command prompt and type  ant -f build_htmlhelp.xml. You should get output with the default CSS  styling.

    Next, modify your Ant build script with the following parameters:  args.copycss, args.css, and args.csspath. All these parameters are documented in  the Open Toolkit but I still wanted a code example that put it all together. So  here it is, and you can copy and paste this into your Ant build file for HTML  Help (CHM).


    <property name="args.copycss" value="yes"/>


    <property name="args.css"


    <property name="args.csspath" value="css"/>


    Now your CSS file will be substituted before the compile command occurs,  which was like magic to me. I had originally thought I'd have to do a  command-line method with quick file copies at the right times, but these Ant  builds are da bomb. The more I learn about using Ant to build DITA output the  more excited I am about the possibilities. Put your DTD specialization files  anywhere! And then point to them using the catalog-dita_template.xml  file! And then build output from anywhere! And substitute your own CSS!


    Recently there has been a discussion on the dita-users Yahoo Group about  styling the CSS for the Table of Contents (TOC) for the XHTML output, and  there's now a patch that enables the substitution of your own CSS for the  Table of Contents. The .patch file is for use with a GNU utility called patch  (Windows version is downloadable from, but you can also read the  .patch file to figure out which modifications to make where.


    Have fun with your own customizations. Let us know if you have any other tips  and tricks with customizing the DITA output.