Customization Example: Apply Custom Styling to an External Transformation

Suppose that you want to apply custom styling to an external DITA transformation using the Oxygen XML WebHelp plugin for DITA OT. The following procedure provides an example of how you could achieve this using a custom CSS file and some of the Oxygen XML WebHelp plugin parameters.

External Transformation Customization Example

To apply your own custom styling to an external DITA transformation using Oxygen XML WebHelp plugin, follow these steps:

  1. Download and install a Java Virtual Machine version compatible with the DITA-OT version.
  2. Download and unpack the DITA Open Toolkit version 1.8.5 or 2.4.4.
  3. Go to Oxygen XML WebHelp website, download the latest DITA-OT version of the installation kit, and unzip it.
  4. Copy all plugin directories from the unpacked archive to the plugins directory of the DITA OT distribution. This is necessary to enable certain functionality. For example, the com.oxygenxml.highlight directory adds syntax highlight capabilities to your WebHelp output for codeblock sections that contain source code snippets (XML, Java, JavaScript).
  5. If you have not already done so, copy your license key into a licensekey.txt file and place it in the DITA-OT-DIR/plugins/com.oxygenxml.webhelp directory.
  6. In the home directory of the DITA Open Toolkit, run ant -f integrator.xml.
  7. Create a new directory for your custom template (DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/MyCustomTemplate).
  8. Create a new directory for your custom skin (DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/MyCustomTemplate/variants/tree/MyCustomSkin).
  9. Copy the DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/bootstrap/variants/tree/light/skin.css file to the custom skin directory you just created (DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/MyCustomTemplate/variants/tree/MyCustomSkin).
  10. Copy the DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/bootstrap/variants/tree/light/resources directory to the custom skin directory you just created (DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/MyCustomTemplate/variants/tree/MyCustomSkin).
  11. Use your system command console to run a command in the DITA-OT-DIR/bin folder that will invoke the external transformation and include the Oxygen XML WebHelp plugin parameters that you desire for your customization.

    For example: dita.bat -i c:\myMap.ditamap -f webhelp-responsive -Dwebhelp.responsive.template.name=MyCustomTemplate -Dwebhelp.responsive.variant.name=tree -Dwebhelp.responsive.skin.name=MyCustomSkin -Dargs.breadcrumbs=yes -Dwebhelp.logo.image=c:\Mylogo.png -Dwebhelp.show.side.toc=no -Dwebhelp.show.top.menu=yes -o c:\MyOutputDirectory

  12. Check the output directory to make sure it now contains your custom skin directory.
  13. Modify the DITA-OT-DIR/plugins/com.oxygenxml.webhelp/templates/dita/MyCustomTemplate/variants/tree/MyCustomSkin/skin.css file according to your needs and check the output to make sure your custom styles are applied properly.