Show Page Sections

Developing a DITA-OT Plugin

You can develop your own DITA-OT plugins to extensively customize your deliverables in various formats.

Tip: Building a plugin on your own requires some knowledge of XSLT, XSL:FO, and CSS. If you want to create a DITA-OT PDF plugin, consider generating it by using the DITA-OT PDF Plugin Generator first. Then, you can modify the generated plugin to better suit your needs.

Default Plugins

The DITA-OT comes with a set of default plugins that can transform your content to various formats such as PDF or HTML5. The default plugins have basic styling applied. You can create custom plugins to apply styling and branding to the default plugins.

Figure 1. Default DITA OT 3.4 Plugins.
Tip: To check the available plugins on your local DITA-OT instance, you can enter the following into shell: dita --plugins.

By default, the DITA-OT 3.4 includes the following plugins:

org.dita.base
org.dita.eclipsehelp
org.dita.html5
org.dita.htmlhelp
org.dita.index
org.dita.normalize
org.dita.pdf2
org.dita.pdf2.axf
org.dita.pdf2.fop
org.dita.pdf2.xep
org.dita.specialization.dita11
org.dita.xhtml
org.lwdita
org.oasis-open.dita.v1_2
org.oasis-open.dita.v1_3
org.oasis-open.xdita.v0_2_2

Plugins Development

The most common way of developing custom a DITA-OT plugin is to extend the default plugin (for example org.dita.html5).
Remember: The most important guideline is not to edit the default plugins files. Instead of that, you create a new plugin folder and custom files that you overwrite the original plugin files with.

For more information, development conventions, and good practices, see Working with Plugins.

Develop a DITA-OT Plugin

You can develop a DITA Open Toolkit plugin by customizing a default DITA-OT plugin.

Choose a framework for your plugin development:
  1. Identify the plugin that you want to use as a base for your plugin.

    In most cases, we recommend to pick a default DITA-OT plugin as a base for your plugin.

    Tip: Basing your plugin on an existing plugin greatly reduces the amount of development work while maintaining the same level of flexibility as developing a completely new plugin.
Create custom plugin folders and files:
  1. Create a directory for your plugin in the plugins directory of your local DITA-OT.
    Tip: If you want to avoid overwriting the default DITA-OT plugins, you can:
    • Make the original plugin folders read-only.
    • Develop your plugin outside the DITA-OT directory and copy your plugin folder to the DITA-OT directory when you complete your plugin development.
    For example, create the com.custom.pdf directory in the C:\DITA-OT\plugins directory.
    DITA-OT
    |-plugins
      |-com.custom.pdf
      |-org.dita.html5
      |-org.dita.pdf2
      |-...
  2. In the plugin directory, create the core files for your plugin by doing the following:
    1. Create and edit the plugin.xml file. See plugin.xml.
      com.custom.pdf
      |-plugin.xml
    2. Create and edit the integrator.xml file. See integrator.xml.
      com.custom.pdf
      |-plugin.xml
      |-integrator.xml
  3. In the plugins directory, create custom plugin files that will override the base plugin files.
    Important: The custom plugin files contain your customizations that override the base plugin styling. The custom plugin files must be specified in the integrator.xml file.
    Depending on the base plugin type that you customize, you can find more information about available customizations under the following links:

plugin.xml

The plugin.xml file specifies the basic information about your plugin.

Template

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="dita-ot/plugin.rnc" type="application/relax-ng-compact-syntax"?>

<plugin id="plugin_id">
  <require plugin="plugin_required"/>
  <transtype name="transtype" extends="extended_transtype" desc="plugin_description" />
  <feature extension="ant.import" file="integrator.xml" />
</plugin>
Table 1. Reference
VariableDescriptionExample
plugin_idPlugin identifier.

The plugin identifier should match the plugin folder name.

com.custom.pdf
plugin_requiredThe base plugin identifier that you modify.

In most cases, the base plugin identifier matches the base plugin folder name.

org.dita.pdf2
transtypeThe name of the transformation type. You use the transformation type when publishing your DITA content.custom-pdf
extended_transtypeThe name of the transformation type that your plugin extends. This is the transformation type associated with the base plugin that you modify.pdf2
plugin_descriptionThe description of the plugin.PDF styled by KRN-Solutions &#169;

integrator.xml

The integrator.xml file specifies your plugin properties and customization files locations.

Template

<?xml version="1.0" encoding="UTF-8" ?>

<project>
  <target name="dita2transtype" depends="dita2transtype.init, dita2extended_transtype />
  <target name="dita2transtype.init">
    <property name="customization.dir" location="${dita.plugin.com.plugin_id}/customization_dir" />
    properties
  </target>
</project>
Table 2. Reference
VariableDescriptionExample
transtypeThe name of the transformation type. You use the transformation type when publishing your DITA content.custom-pdf
extended_transtypeThe name of the transformation type that your plugin extends. This is the transformation type associated with the base plugin that you modify.pdf2
plugin_idPlugin identifier.

The plugin identifier should match the plugin folder name.

com.custom.pdf
customization_dirThe customization directory of your plugin. The customization directory should reflect the base plugin structure.cfg
propertiesFor more information about the available properties, see https://www.dita-ot.org/dev/parameters/parameters_intro.html.
  • <property name="nav-toc" value="full" />
  • <property name="args.rellinks" value="all"/>