DITA Open Toolkit

The DITA-OT 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 formats1:

  • 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.

Publish Content with the DITA Open Toolkit

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

  1. In the content library, click on a map, and in the right pane select Output and click Publish.
  2. From the list on the left, select a DITA-OT publishing scenario.
    The publishing scenarios are configured by your CCMS 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.
    Transformation Type (or Output Type)
    Enables you to select the output format.
    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.
    Track changes
    Include or exclude tracked changes (suggestions) from the Content Editor in the output.
    Note: By default, this feature may not be available. For more information, contact your Customer Success Manager.

    For more information about the DITA Open Toolkit (DITA-OT) 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 with the DITA Open Toolkit

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.
Note: This functionality may be disabled on your Heretto CCMS instance. For more information, contact your Customer Success Manager.
  1. In the content library, click on a map, and in the right pane select Output and click Publish.
  2. From the list on the left, select a DITA-OT publishing scenario.
    The publishing scenarios are configured by your CCMS 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 (DITA-OT) 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. Heretto CCMS uses the publishing parameters of the previous publishing job.
  1. In the content library, click on a map, and in the right pane select Output and click Publish.
  2. Click the previous publishing job that you want to republish.
    The Publish window appears.
  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-OT 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 Main Menu, click Plugins.
  2. If needed, select DITA-OT.
  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-guides/22/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.
  5. Add publishing scenario parameters by doing the following:
    1. Click Add a Parameter.
    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 X icon icon enables you to remove a value.

      Figure 1. User Select Box Parameter.

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

      User select box parameter
      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 2. File Reference Parameter.

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

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

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

      Runtime File Picker Parameter example
  6. If needed, add another parameter by repeating 5.
  7. If needed, remove a parameter by clicking the corresponding "X" icon.
  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.
  9. Click Save.
Your publishing scenario is now available in the publishing interface.

Upload a DITA-OT Plugin

Administrators can upload DITA-OT 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 4. 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.

DITA OT Plugin Folder
  1. In the Main Menu, click Plugins.
  2. If needed, select DITA-OT.
  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-OT 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 Main Menu, click Plugins.
  2. If needed, select DITA-OT.
  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.
1 The available transformation types depend on the DITA-OT version and DITA-OT plugins.