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.
Build a Plugin
Learn how to build a plugin to customize your PDF output.
Upload a Plugin
Upload a DITA Open Toolkit plugin to customize your output.
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.
section
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:
Build a Plugin

Learn how to build a plugin to customize your PDF output.
You can build a plugin to customize your PDF output. Building a plugin from scratch enables you to customize as much as you want, but requires some knowledge of XSLT and CSS. Then once the plugin is built, you can upload it into easyDITA and use it when publishing.
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.  
Get started by creating a plugin using the PDF Plugin Generator. Then, if there are any additional customizations you want, use the easyDITA PDF Customizations.
Upload a Plugin

Upload a DITA Open Toolkit plugin to customize your output.
context

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. In the Administration interface, click Plugins .

    Step Information

    Expected Result
    The Plugins interface displays.

  3. Select DITA Open Toolkit.

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

  4. In the DITA OT Plugins list, click New.

    Step Information

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

    Step Information
  6. Click Done .
result

You have a new plugin available to be used in publishing scenarios.

postreq
Make sure you have the corresponding DITA Open Toolkit version the plugin is built on in easyDITA. If not, then you’ll need to also upload the DITA Open Toolkit. If you already have the DITA Open Toolkit in easyDITA, you’re ready to set up a publishing scenario.
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.
prereq
If you’re setting up a publishing scenario with a custom DITA Open Toolkit plugin, you’ll need to upload the plugin and the corresponding DITA Open Toolkit before creating the publishing scenario.
context
You’re logged in as an administrator in the Dashboard interface and want to set up a publishing scenario.
  1. In the Administration interface, click Plugins .

    Step Information

    Expected Result
    The Plugins interface displays.

  2. Select DITA Open Toolkit.

    Expected Result
    The Configure the DITA Open Toolkit 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. In the Scenario Name field , enter a name for your publishing scenario. This will be visible to end users when selecting a scenario in the Publishing interface.
    2. In the Select DITA Open Toolkit drop-down menu , select a DITA Open Toolkit to use with this scenario.

      Step Information
      Remember:If you’re using a custom plugin in this scenario, you’ll need to upload the corresponding DITA Open Toolkit version the plugin is built on.
    3. In the Select Ant File to Run field , click Change and 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. For example, transtype.

      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 the 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 screen and your new scenario is listed in the Scenarios list.

result

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