Edit online

Customizing DITA Transformations

You can customize the appearance of any of the output types by customizing the output transformations. There are several ways to do this:
  • Most transformations are configurable by passing parameters to the transformation script. Oxygen XML Author Eclipse plugin allows you to set parameters on a transformation scenario and you can save and share them with others. You can also use the ${ask} editor variable in the Parameters tab to instruct Oxygen XML Author Eclipse plugin to prompt you for a particular parameter whenever a transformation scenario is run. You can set up multiple transformation scenarios for a given output type, allowing you to maintain several customized transformation scenarios for multiple types of output configurations.
  • If you want to customize an output in a way not supported by the built-in customization options, you can create a modified version of the transformation code and execute it using a custom build file. Sometimes the transformation code exports specific forms of extensions or customizations. You should consult the DITA Open Toolkit for the transformation type that you are interested in to see what customization options are supported.
  • You can also write your own transformation code (and execute it using a custom build file) to produce a type of output not supported by the DITA Open Toolkit. You can create Oxygen XML Author Eclipse plugin transformation scenarios to run these scripts once they are complete.
There are also many other ways to customize specific types of output generated from DITA transformations:

Publishing Customizations

Some customizations (usually for HTML-based output), can be made simply by creating a custom CSS and they do not involve modifying the DITA-OT engine in any way. Instead, most customizations involve adding a new plugin to the DITA-OT. Here are some best practices to follow before beginning your customization:
  1. Copy the bundled DITA-OT folder (usually OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT) to a location where you have full write access so that you have the ability to install new DITA-OT plugins.
  2. Go to Options > Preferences > DITA, select Custom for the DITA Open Toolkit option and set the Location to be the path to the location where you copied the bundled DITA-OT folder. This will allow you to upgrade the version of Oxygen XML Author Eclipse plugin at anytime without affecting the publishing system.
  3. Share that external DITA-OT folder with the rest of the team. If you are using a repository (such as Subversion or Git), you can commit the entire modified DITA-OT publishing engine as part of your project. This will allow everyone in your team to use the official changes that you made. This will also allow you to set up some kind of automatic publishing system using an open-source integration server (such as Travis CI or Jenkins).

Customizing XHTML-based Output

XHTML-based output can be modified by using a custom CSS stylesheet to override various styles. If you edit an XHTML transformation scenario, there is a parameter called args.css that can be set to point to your custom CSS and a parameter called args.copy.css that as long as it is set to yes, the CSS is copied to the output folder.

You can also create plugins to customize the XHTML-based output by adding an extra XSLT stylesheet. For for information, see: https://blog.oxygenxml.com/topics/creating-simple-dita-open-toolkit.html. A list with all DITA-OT XSLT extension points can be found here: http://www.dita-ot.org/dev/extension-points/plugin-extension-points-xslt-import.html.

Customizing WebHelp-based Output

The DITA-OT that comes bundled in Oxygen XML Author Eclipse plugin includes specific plugins that provide the ability to publish DITA content to WebHelp Responsive output.

For information about customizing WebHelp Responsive output, see Customizing WebHelp Responsive Output.

Customizing PDF-based Output

DITA to PDF output can be customized either by creating a PDF customization folder (in this case, the DITA-OT folder will not be modified at all) or by creating a PDF customization plugin. For information about customizing DITA to PDF output, see XSL FO-based DITA to PDF Customization.

There is also a book called DITA For Print that contains details about how to customize various aspects.

Customizing PDF Output with CSS

Oxygen XML Author Eclipse plugin also includes a transformation scenario called DITA Map PDF - based on HTML5 & CSS that is based on a DITA-OT CSS-based PDF Publishing plugin that allows you to convert DITA maps to PDF using a CSS layout processor. For those who are familiar with CSS, this makes it very easy to style and customize the PDF output of your DITA projects without having to work with xsl:fo customizations. For more information about customizing PDF output using this transformation scenario, see Customization CSS.