DITA Open Toolkit

The DITA Open Toolkit is an open publishing engine that converts DITA content into multiple formats.

DITA-OT Capabilities

Out of the box, the DITA-OT enables you to publish to the following formats:

  • PDF
  • HTML5
  • XHTML
  • HTML Help ePub
  • eBook
  • JavaHelp
  • RTF

By default, the DITA-OT enables you to publish content with simple styling applied. The publishing capabilities can be expanded by adding the DITA-OT plugins that enable you to produce branded and styled output.

Tip: You can develop the DITA-OT plugins on your own or use our professional services. We can also recommend partner vendors who provide the DITA-OT customization services.

For more information, see Upload a DITA-OT Publishing Engine.

Publish Content with the DITA-OT

The DITA Open Toolkit enables you to publish content to various formats.

  1. In the content library, hover over a map, click the Output icon, and click Publish.
  2. From the list on the left, select a DITA-OT publishing scenario.
    The publishing scenarios are configured by your easyDITA administrator.
  3. Optional: In the Enter Description field, enter a meaningful description.
    Once you publish the document, this description appears in the list of finished publishing jobs.
  4. Set the publishing parameters.
    The publishing scenario can include the following parameters.
    Ditaval (or args.filter)
    Enables you to select a DITAVAL file for conditional publishing.
    Locales
    Enables you to select a locale when publishing localized content.
    Webhooks
    Enables you to send webhooks on successful publish or any publish.
    Debug publish
    Generates additional files in the debug folder that you can use to troubleshoot your publication.

    For more information about the DITA Open Toolkit parameters, see https://www.dita-ot.org/dev/parameters/parameters_intro.html.

  5. Click Publish.
    The resource publishes. It may take a moment to complete.
  6. Download the published files by hovering over the publishing job and clicking the Download icon.

Publish a PDF Comparison

You can publish a PDF that compares the current content with the content in a branch or release.

Create a release or branch a map.
  1. In the content library, hover over a map, click the Output icon, and click Publish.
  2. From the list on the left, select a DITA-OT publishing scenario.
    The publishing scenarios are configured by your easyDITA administrator. For more information, see DITA-OT Publishing Scenarios Management.
    Important: You can only publish a PDF comparison by using a PDF publishing scenario based on DITA Open Toolkit version 2.x or greater.
  3. Optional: In the Enter Description field, enter a meaningful description.
    Once you publish the document, this description appears in the list of finished publishing jobs.
  4. From the Compare to drop-down menu , select a branch or release to compare the current content with.
  5. Set the rest of the publishing parameters.
    The publishing scenario can include the following parameters.
    Ditaval (or args.filter)
    Enables you to select a DITAVAL file for conditional publishing.
    Webhooks
    Enables you to send webhooks on successful publish or any publish.
    Debug publish
    Generates additional files in the debug folder that you can use to troubleshoot your publication.

    For more information about the DITA Open Toolkit parameters, see https://www.dita-ot.org/dev/parameters/parameters_intro.html.

  6. Click Publish.
    The resource publishes. It may take a moment to complete.
  7. Download the published files by hovering over the publishing job and clicking the Download icon.
The PDF output file highlights content differences with red and green.

Republish Content

You can republish a previous publishing job to troubleshoot publishing issues or apply new changes to the published output.

CAUTION: Republishing a publishing job replaces the previous output with the new output. easyDITA uses the publishing parameters of the previous publishing job.
  1. In the content library, hover over a map, click the Output icon, and click Publish.
  2. Click the previous publishing job that you want to republish.
    The Publish window appears.
    Figure 1. Publishing Job Details
  3. In the top-right corner, click and select Republish .

DITA-OT Publishing Scenarios Management

Create a DITA-OT Scenario

Administrators can create the DITA Open Toolkit publishing scenarios by using the Plugins interface.

Do the following:
  • If needed, upload the plugin that you want to use in the publishing scenario. See Upload a DITA-OT Plugin.
  • If needed, upload the required DITA-OT publishing engine version. See Upload a DITA-OT Publishing Engine.
    Remember: Some DITA-OT plugins may require a specific version of the DITA-OT publishing engine. You can use different DITA-OT publishing engines and plugins in different publishing scenarios.
  1. In the Dashboard, click Plugins .
  2. If needed, select DITA Open Toolkit.
  3. In the Scenarios list, click New .
  4. In the Add a New Publishing Scenario screen, do the following:
    1. Fill in the Scenario Name field.
    2. From the Select DITA Open Toolkit drop-down menu, select a DITA-OT publishing engine version that you want to use.
    3. From the DITA OT Version drop-down menu, select the version of the DITA-OT publishing engine that you selected in /user-guide/publish/dita-open-toolkit#task-4823__substep_uls_jqs_pkb.
    4. Near the Select Ant File to Run field, click Change and select the build file.
      Tip: The default ANT file is the build.xml file in the main directory of a DITA-OT publishing engine.
      Figure 2. File Picker.

      In the following example the build.xml file is directly in the dita-ot-3.4 directory.

  5. Add publishing scenario parameters by doing the following:
    1. Click Add a Parameter .
      Figure 3. Parameter Entry
    2. Fill in the Parameter Name field.
      For more information on available parameters, see https://dita-ot.org.
      A common parameter is transtype. It lists transformation types. Enter pdf, html5, or htmlhelp).
    3. From the Select Parameter Type drop-down menu, select a parameter type set the related options.
      Simple String Value
      Enables you to enter a value for a parameter. By default the value cannot be changed while publishing.

      The User Settable? option enables you to change the value while publishing.

      User Select Box
      Enables you to provide different values of a given parameter. You can choose from these values while publishing.

      The Add Option button enables you to add more values. The icon enables you to remove a value.

      Figure 4. User Select Box Parameter.

      In the following example, the args.draft parameter values yes or no can be selected while publishing.

      File Reference
      Enables you to provide a path to a file as a value of a given parameter. The value cannot be edited while publishing.
      Figure 5. File Reference Parameter.

      In the following example, the args.css parameter value is a file path to the custom.css file.

      Runtime File Picker
      Enables you to select a file used as the parameter value while publishing.
      Figure 6. Runtime File Picker Parameter.

      In the following example, the args.filters value can be set while publishing by selecting a file.

  6. If needed, add another parameter by repeating 5.
  7. If needed, remove a parameter by clicking the corresponding .
  8. If you use custom plugins in the publishing scenario, in the Select DITA OT Plugins pane on the right, ensure that the custom plugins are selected.
    Figure 7. Selected Custom Plugin
  9. Click Save .
    Figure 8. Publishing Scenario Example
Your publishing scenario is now available in the publishing interface.

Upload a DITA-OT Plugin

Administrators can upload DITA Open Toolkit plugins.

Remember: Some DITA-OT plugins may require a specific version of the DITA-OT publishing engine. You can use different DITA-OT publishing engines and plugins in different publishing scenarios.
Obtain a ZIP file that contains a DITA-OT plugin.
Important: The ZIP file must contain a singular plugin folder in the root directory.
Figure 9. Zipped DITA OT Plugin.

In the following example, the main folder of a custom DITA-OT plugin is directly in the ZIP file root directory.

  1. In the Dashboard, click Plugins .
  2. If needed, select DITA Open Toolkit.
  3. Next to the DITA OT Plugins list, click New .
  4. In the Upload New Plugin window, click Browse and select the zipped plugin. Click Open.
Use the DITA-OT plugin in a DITA-OT publishing scenario. See Create a DITA-OT Scenario.

Upload a DITA-OT Publishing Engine

Administrators can upload a DITA Open Toolkit version of their choice.

Remember: Some DITA-OT plugins may require a specific version of the DITA-OT publishing engine. You can use different DITA-OT publishing engines and plugins in different publishing scenarios.
  • Obtain a ZIP file that contains a DITA-OT publishing engine.
    Tip: You can download different versions of a DITA-OT publishing engine from https://www.dita-ot.org/download
  1. In the Dashboard, click Plugins .
  2. If needed, select DITA Open Toolkit.
  3. Next to the Available DITA Open Toolkits list, click New .
  4. Click Browse and select the zipped DITA-OT publishing engine.
  5. Click Open
The DITA-OT publishing engine that you uploaded shows in the Available DITA Open Toolkits list.
Use the DITA-OT publishing engine in a DITA-OT publishing scenario. See Create a DITA-OT Scenario.