DITA-OT Plugins Development

Local DITA-OT Overview

You can install the DITA Open Toolkit publishing engine locally to quickly test and troubleshoot your plugins without the need to upload them to easyDITA.

Overview

The DITA-OT is a command-line utility. You operate the local DITA-OT by using your operating system shell. The DITA-OT runs on Windows, macOS, and Linux.

Shell

Each major operating system has a built-in shell application that enables you to interact with the DITA Open Toolkit from the command line.

Figure 1. Windows Command Prompt.
Tip: You can open the command prompt by pressing the Start key and entering `cmd`

Figure 2. macOS Terminal.
Tip: You can open the terminal by pressing Cmd > Space and entering `terminal`

Figure 3. Linux Terminal.
Tip: On Ubuntu 19.10, you can open the terminal by pressing the Super key and entering `terminal`

Operation

You use the DITA-OT by entering dita at the command prompt followed by any applicable arguments.

Tip: For the complete list of the dita arguments, at the prompt, enter dita -h

Install DITA-OT Locally

The DITA Open Toolkit installation is slightly different for Windows, macOS, and Linux.

In your web browser, go to https://www.dita-ot.org/dev/topics/installing-client.html.
On the DITA-OT documentation site, from the Version drop-down list, select the DITA-OT version that you want to install.

Figure 4. DITA-OT Documentation

Remember: DITA-OT plugins may require specific versions of the DITA-OT publishing engine to operate properly. In easyDITA, you can use different DITA-OT publishing engines and plugins in different publishing scenarios. We recommend using the current version of the DITA-OT publishing engine.
Install the DITA-OT by using the instructions on the following DITA Open Toolkit site: https://www.dita-ot.org/dev/topics/installing-client.html.

Important: For macOS and Linux, if possible, we recommend using Homebrew to install the latest DITA-OT.
Ensure that you added the path to the DITA-OT bin directory to the PATH system variable. See Run the DITA Command from Anywhere.
Open the shell application by doing one of the following:
- For Windows, press the Start key and enter cmd
- For macOS, press Cmd > Space and enter terminal
- For Linux (Ubuntu 19.10), press the Super key and enter terminal
At the prompt, ensure that you properly installed the DITA-OT by entering dita -v
The version of the local DITA-OT appears.

Run the DITA Command from Anywhere

Adding the DITA-OT to the PATH system variable enables you to run the dita command from any location in the system.

Install the DITA-OT publishing engine locally. See Install DITA-OT Locally.

Important: For macOS, if you installed the DITA-OT via Homebrew, you can skip this procedure.

For Windows, do the following:
1. Click Start and enter environment variables
2. Select Edit the system environment variables.
3. In the System Properties window, click Environment Variables.
4. In the Environment Variables window, under System variables, double-click Path.
5. In the Edit environment variable window, click New.
6. Enter <DITA_OT_bin_directory>
  Where: <DITA_OT_bin_directory> is the full path to the DITA-OT bin directory on your local drive.
7. In each window, click OK.
For macOS, do the following:
1. Press Cmd > Space .
2. Enter terminal
3. Press Enter .
4. Enter sudo nano /etc/paths
5. Enter the administrator password.
6. At the bottom of the file, add the full path to the DITA-OT bin directory on your local drive.
  Enter: /Applications/dita-ot-3.4/bin
7. Press Control > X
8. Press Y
9. Press Enter .
10. Close the Terminal window.

Install a DITA OT Plugin Locally

You can install a DITA Open Toolkit plugin by moving the plugin folder and running the dita --install command.

Before you begin, do the following:

Install the DITA Open Toolkit publishing engine locally. See Install DITA-OT Locally.
Obtain the plugin that you want to install on your local DITA-OT instance.
Tip: You can generate or develop your own DITA-OT plugins. For more information, see integrator.xml and Developing a DITA-OT Plugin.

Copy the plugin folder to the Plugins folder of the local DITA-OT.
For example copy the plugin folder to:
- C:\dita-ot-3.4\plugins (Windows)
- /Applications/dita-ot-3.4/plugins (Mac)
Open the shell application by doing one of the following:
- For Windows, press the Start key and enter cmd
- For macOS, press Cmd > Space and enter terminal
- For Linux (Ubuntu 19.10), press the Super key and enter terminal
Note: If you added DITA to the PATH system variable, you can skip this step.
At the prompt, enter cd DITA_OT_bin_directory
Where: DITA_OT_bin_directory is the full path to the DITA-OT bin directory on your local drive.
For example, enter:
- C:\dita-ot-3.4\bin (Windows)
- /Applications/dita-ot-3.4/bin (Mac)
At the prompt, enter dita --install
The local DITA-OT updates the available plugins.

Publish Content with Local DITA-OT

You can transform the DITA source to various output formats by using a local instance of the DITA Open Toolkit.

Note: The following procedure shows the simplest dita command that you can use to publish content locally. For more information, see the DITA-OT documentation on https://www.dita-ot.org.

Before you begin, do the following:

Install the DITA-OT publishing engine locally. See Install DITA-OT Locally.
If needed, install the DITA-OT plugin that you want to use in publishing. See Install a DITA OT Plugin Locally.

Open the shell application by doing one of the following:
- For Windows, press the Start key and enter cmd
- For macOS, press Cmd > Space and enter terminal
- For Linux (Ubuntu 19.10), press the Super key and enter terminal
Note: If you added DITA to the PATH system variable, you can skip this step.
At the prompt, enter cd DITA_OT_bin_directory
Where: DITA_OT_bin_directory is the full path to the DITA-OT bin directory on your local drive.
For example, enter:
- C:\dita-ot-3.4\bin (Windows)
- /Applications/dita-ot-3.4/bin (Mac)
Enter the following into shell: dita --input "dita_source_path" --format transtype --output "out_folder_path"
Where:
- dita_source_path is the full path to the map or a topic that you want to publish.
  Some DITA-OT plugins may require a map to publish content properly. If you want to publish a single topic, we recommend including it in a map and publishing that map.
- transtype is the transformation type defined in the plugin that you want to use
  For example:
  - One of the default transtypes, including: pdf2, html5, or javahelp
  - Any custom transtype
- out_folder_path is the full path to the output folder
Example:
```
dita --input "C:\LocalFiles\GitHub\XML\source\Technical_Writing_Environment_Setup_Guide\Technical_Writing_Environment_Setup_Guide.ditamap" --format html5 --output "C:\LocalFiles\GitHub\XML\source\Technical_Writing_Environment_Setup_Guide\out"
```
Figure 5. Output Example

Generating a DITA-OT PDF Plugin

You can use the DITA-OT PDF Plugin Generator to quickly create customized PDF plugins.

Tip: Generating a PDF plugin by using the DITA-OT PDF Plugin Generator is much easier than developing one from scratch. If needed, you can extend the generated plugin with some custom development work.

DITA-OT Plugin Generator

The DITA-OT Plugin Generator is a free online tool that enables you to easily build custom DITA-OT PDF plugins.

Generate a DITA-OT PDF Plugin

The DITA-OT PDF Plugin Generator enables you to quickly create custom PDF plugins for the DITA Open Toolkit.

In your web browser, go to https://dita-generator.elovirta.com/.

Figure 6. Target Environment Page
On the Target environment page, do the following:
1. From the DITA-OT version drop-down menu, select one of the available DITA-OT publishing engines.
  
  Remember: DITA-OT plugins may require specific versions of the DITA-OT publishing engine to operate properly. In easyDITA, you can use different DITA-OT publishing engines and plugins in different publishing scenarios. We recommend using the newest DITA-OT publishing engines available.
2. From the XSL formatter drop-down menu, select a PDF rendering engine.
  Different XSL formatters support different plugin customization features. The FOP formatter is free. The AntennaHouse Formatter and ReaderX XEP are paid.
3. Select the Override shell check box.
  Overriding the XSLT shell stylesheet makes it easier to modify the generated plugin after its created.
4. Click Next.
Configure the page, margin, and column settings, as appropriate. Click Next.

Figure 7. Page, Margins, and Columns Settings
Configure the header and footer formatting. Click Next.

Figure 8. Header
Configure the basic body content styles. Click Next.
Configure the outstanding styling options. Click Next.
On the Metadata page, do the following:
1. In the Plug-in ID field, enter a plugin name.
  
  Remember: We recommend that the plugin name contains the transtype name.
  
  Enter com.minimal-blue.pdf
2. In the Transtype field, provide a transtype name.
  Important: Transtypes (transformation types) define the output. The transtype name must be unique within the plugins for a given DITA-OT.
  You will need the transtype name to:
  - Add a new DITA-OT publishing scenario in easyDITA
  - Publish content by using a local DITA-OT instance
  Enter minimal-blue and remember the transtype.
3. Optional: Fill in the Plug-in version.
  Enter 1.0
4. Click Generate.
  A ZIP file that contains your plugin downloads automatically.

To apply advanced customizations to your plugin. See Developing a DITA-OT Plugin.

Developing a DITA-OT Plugin

You can develop your own DITA Open Toolkit 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 9. 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.

Install the DITA-OT on your workstation. See Install DITA-OT Locally.
Note: The DITA-OT installs with a set of default plugins that you can use as base plugins for your own plugins development.
Review the best practices recommended for plugin development. See https://www.dita-ot.org/dev/topics/plugin-best-practices.html.

Choose a framework for your plugin development:

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:

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
  |-...
```
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
```
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:
- If you customize the org.dita.pdf2 base plugin or a generated PDF plugin, seehttps://www.dita-ot.org/dev/topics/pdf-customization.html.
- If you customize the org.dita.html5 or the org.dita.xhtml base plugin, see https://www.dita-ot.org/dev/topics/html-customization-plugins.html.
- If you customize a different base plugin, analyze the base plugin files and customize them accordingly.

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
Variable	Description	Example
`plugin_id`	Plugin identifier. The plugin identifier should match the plugin folder name.	`com.custom.pdf`
`plugin_required`	The base plugin identifier that you modify. In most cases, the base plugin identifier matches the base plugin folder name.	`org.dita.pdf2`
`transtype`	The name of the transformation type. You use the transformation type when publishing your DITA content.	`custom-pdf`
`extended_transtype`	The name of the transformation type that your plugin extends. This is the transformation type associated with the base plugin that you modify.	`pdf2`
`plugin_description`	The description of the plugin.	`PDF styled by KRN-Solutions ©`

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
Variable	Description	Example
`transtype`	The name of the transformation type. You use the transformation type when publishing your DITA content.	`custom-pdf`
`extended_transtype`	The name of the transformation type that your plugin extends. This is the transformation type associated with the base plugin that you modify.	`pdf2`
`plugin_id`	Plugin identifier. The plugin identifier should match the plugin folder name.	`com.custom.pdf`
`customization_dir`	The customization directory of your plugin. The customization directory should reflect the base plugin structure.	`cfg`
`properties`	For 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"/>`

What would you like to learn today?

Here you will find all the resources related to using easyDITA.

DITA-OT Plugins Development

Local DITA-OT Overview

Overview

Shell

Operation

Install DITA-OT Locally

Run the DITA Command from Anywhere

Install a DITA OT Plugin Locally

Publish Content with Local DITA-OT

Generating a DITA-OT PDF Plugin

DITA-OT Plugin Generator

Generate a DITA-OT PDF Plugin

Developing a DITA-OT Plugin

Default Plugins

Plugins Development

Develop a DITA-OT Plugin

plugin.xml

Template

integrator.xml

Template