Table of Contents
More Resources
DITA Open Toolkit PDF Output Customization
Overview
Learn how to customize your PDF output by building a plugin yourself or using a plugin generator.
Use the PDF Plugin Generator
PDF Plugin Generator, Generate a Plugin, PDF Plugin Generator Customizations
Build a Plugin
Building a Plugin, Build a Plugin, easyDITA PDF Customizations
Upload a Plugin
Upload a DITA Open Toolkit plugin to customize your output.
Upload a DITA-OT
Set up a Publishing Scenario
Before you can publish with the DITA Open Toolkit, an administrator needs to set up publishing scenarios that will be selected by users to publish DITA topics and maps.
Overview

Learn how to customize your PDF output by building a plugin yourself or using a plugin generator.
The DITA Open Toolkit uses the default PDF2 plugin to transform DITA content to PDF. This plugin contains basic PDF styling. If your PDF ouput requires a company logo, a specific header and footer, or specific spacing, you’ll need to create a custom plugin to customize your PDF output. You can build a plugin yourself or use a plugin generator.
We recommend you Use the PDF Plugin Generator first. The plugin generator enables you to easily preview and select your customizations. Once you’ve selected your customizations, it generates the plugin with the correct customization files in a zipped folder. Then if there are additional customizations you want that aren’t available in the generator, you can easily add easyDITA PDF Customizations to the generated plugin instead of having to Build a Plugin from scratch. Once your customization plugin is ready, you can upload it into easyDITA and add it to a publishing scenario.
This guide shows you how to create a custom plugin. You can either:
Once your plugin is built, you’ll need to:
Let’s get started with building a plugin, Use the PDF Plugin Generator or Build a Plugin yourself.
Upload a Plugin

Upload a DITA Open Toolkit plugin to customize your output.
You’re logged in as an administrator in the Dashboard interface and want to upload a DITA Open Toolkit plugin.
  1. Create a ZIP folder containing only your plugin’s directory

    Example

    If you have been prototyping your plugin locally, you need to zip up the folder located at DITAOT-{version}/plugins/{your-plugin-name}.

  2. Under Administration, click Plugins.

    Step Information

    Expected Result
    The Plugins interface displays.

  3. Select DITA Open Toolkit.

    Expected Result
    The Configure the DITA Open Toolkit Plugin screen displays and lists all available scenarios, DITA OTs, and plugins.

  4. In the Plugins list, click New.

    Step Information

  5. Click Browse and then navigate to and select the zip file.

    Step Information
  6. Click Done.
You have a new plugin available to be used in publishing scenarios.
Ensure you have the corresponding DITA Open Toolkit version the plugin is built on in easyDITA. If not, then you’ll need to Upload a DITA-OT. If you already have the DITA Open Toolkit in easyDITA, you’re ready to Set up a Publishing Scenario.
Upload a DITA-OT

If you’re building your own plugin or using the PDF Plugin Generator to generate a plugin, you’ll need to upload the DITA Open Toolkit version that your plugin is built on so you can use the plugin in easyDITA.
Important:If your custom plugin is built using the DITA-OT version 2.0+, you’ll need the corresponding DITA-OT version in easyDITA. Contact an easyDITA representative to upload and enable the DITA Open Toolkit 2.X on your server. Once enabled, you’ll be able to use the DITA-OT 2.X and your plugin in a publishing scenario.
  1. First, you need to download the DITA-OT version your plugin is built on. You can download your DITA-OT version from the DITA-OT website.

    Step Information
    Note:Use one of the DITA-OT[version]_full_easy_install_bin.zip packages. The “Full Easy Install” packages contain integration hooks that easyDITA relies on.
  2. Next, you need to open the Plugins interface so you can upload the DITA-OT. In the Dashboard interface, click Plugins.

    Expected Result
    The Plugins interface displays.
  3. Click DITA Open Toolkit.

    Expected Result
    The DITA Open Toolkit configurations display.
  4. Beside Available DITA Open Toolkits, click New.
  5. Click Browse, then navigate to and select the DITA-OT you want to upload.
You uploaded the DITA-OT into easyDITA.
Set up a Publishing Scenario

Before you can publish with the DITA Open Toolkit, an administrator needs to set up publishing scenarios that will be selected by users to publish DITA topics and maps.
If you’re setting up a publishing scenario with a custom DITA-OT plugin, you’ll need to Upload a Plugin and Upload a DITA-OT before creating the publishing scenario.
You’re logged in as an administrator in the Dashboard interface and want to set up a publishing scenario.
  1. Under Administration, click Plugins.

    Step Information

    Expected Result
    The Plugins interface displays.

  2. Select DITA Open Toolkit.

    Expected Result
    The Configure the DITA Open Toolkit Plugin screen displays and lists all available scenarios, DITA OTs, and plugins.

  3. In the Scenarios list, click New.

    Expected Result
    The Add a New Publishing Scenario screen displays.

  4. In the Add a New Publishing Scenario screen, do the following:

    1. Enter a Scenario Name. This will be visible to end users when selecting a scenario in the Publication Manager
    2. Select the DITA Open Toolkit to use with this scenario.

      Step Information
      Remember:If you’re using a custom plugin in this scenario, you’ll also need to upload the correspending DITA Open Toolkit version the plugin is built on. For more information, see Upload a DITA-OT.
    3. Select an Ant file to run. Click Change, then select the Build file from the File Picker.

      Step Information
      Note:The default Ant script is “build.xml” in the root of the DITA OT folder.

  5. Click Add a Parameter.

    Step Information

    1. Enter a Parameter Name.

      Step Information

      Parameters must be expected by the Ant file you chose to run. If you selected the default build.xml in the DITA OT, there is a link to the DITA OT Parameter Reference in the right column of the Add a New Publishing Scenario screen.

      Example

      A common parameter is transtype. It lists the transformation types available in the toolkit (e.g. PDF, HTML Help, xhtml, etc.).

    2. Select a Parameter Type.

      Step Information

      There are four parameter types:

      1. Simple String Value
      2. User Select Box
      3. File Reference
      4. Runtime File Picker
      Example

      For the parameter transtype the Parameter Type is User Select Box, which will list a drop down of the transform types.

    • For a Simple String Value, enter a Value. You can allow users to modify a simple string value at publish by selecting the User Settable option.
    • For a User Select Box, you will need to add the Options you want to be present in the Select Box. For each option in the list box, click Add Option, then enter the text that will appear for that option in the list.
    • For a File Reference, click Change to choose a file with the File Picker. You may select files or folders with the file reference.
  6. To add additional parameters, click Add a Parameter, and repeat Step 5.
  7. (Optional) Under Select DITA OT Plugins, select a plugin.

    Step Information
    Remember:If you want to use a plugin in this scenario, you’ll need to Upload a Plugin first.
  8. Once you’ve specified all of the parameters for this scenario, click Save.

    Example
    Here’s an example of a publishing scenario:
    Expected Result

    You return to the Configure the DITA Open Toolkit Plugin screen and your new scenario is listed in the Scenarios list.

The new publishing scenario is now available for users to choose when publishing using the DITA Open Toolkit.