Prepare and Install a Custom DITA Open Toolkit

Preparing a custom DITA Open Toolkit (DITA-OT), and especially developing a custom DITA-OT plugin, requires a specific skill set. If you do not have the skills required to develop a custom plugin, you can learn at dita-ot.org or you can work with a partner. We can recommend partners who provide DITA-OT customization services. All DITA-OT customizations need to be embedded in your toolkit.

This document doesn't explain how to develop a custom plugin.

The default DITA-OT comes with rich functionality but you can extend it to take full advantage of DITA-OT Cloud in Heretto CCMS. Your custom DITA-OT may contain three custom components:

Custom plugins
Custom fonts
Linux-based Antenna House (AH) Formatter

You can add any combination of these three custom components to your DITA-OT for use in Heretto CCMS. However, remember to follow best practices for creating custom toolkits.

Where to Learn about DITA-OT

The top three resources we recommend for those who want to learn how to customize DITA-OT, and especially how to customize DITA-OT plugins, are:

Official DITA-OT web site: dita-ot.org
Google group: DITA-OT Users
Slack group: dita-ot.slack.com

A great way to create a simple custom plugin is by using the free PDF Plugin Generator available at dita-generator.elovirta.com.

Best Practices for Creating Custom Toolkits

Learn how to create custom DITA Open Toolkits (DITA-OT) effectively. Understand the factors influencing publishing times and follow a detailed table of recommendations for optimal configuration.

The way you set up your custom DITA-OT directly affects the publishing time you experience. Every time you publish with DITA-OT Cloud, the service takes 20-30 seconds to start a secure, temporary container into which it uploads all resources needed to publish content. Once the container starts, the service uploads the toolkit related to the publishing scenario and the content itself. The larger the resources, the longer it takes to upload them into the container.

On a high level, a couple factors can cause longer publishing times with DITA-OT Cloud:

Content condition and size

If your content contains unresolved preflight issues like broken links, missing content, unresolved content key references (conkeyref), processing it for publishing takes longer. Always resolve all issues flagged in preflight check before publishing your content. See Preflight Check.

If you publish a large deliverable, it is expected to take more time to publish due to its size.

DITA-OT size

Default DITA Open Toolkits are typically not larger than 30-50 MB. If your toolkit is configured to publish to multiple output types and contains custom resources like fonts or plugins, its size grows quickly which directly affects publishing time. Ensure that you use multiple toolkits, each configured to publish to only one output type like PDF or HTML.

You are in control of these factors. In this section, we focus on best practices for optimizing custom toolkits and mitigating these factors.

The recommendations in this table can help reduce or avoid long publishing times in DITA-OT Cloud. The general rule of thumb is: Keep your toolkits small. Do not add components to a toolkit that are not needed for a specific publishing scenario.

Table 1. Custom DITA-OT Recommendations
A custom toolkit created according to these guidelines is smaller and publishing is faster because the system doesn't need to upload a large toolkit to the temporary container every time a publishing job starts. Uploading a small toolkit takes much less time.
Tip:
You can see the size of your toolkit on the DITA-OT Cloud configuration page in the CCMS Administration interface.
Resource	Recommendation	Avoid	Impact on publishing time
Toolkit version	Use DITA-OT versions 3.6.1 to 3.7.4. They contain parameters that help with processing speed. For more information, go to https://www.dita-ot.org/ and review common parameters for a specific toolkit version. Important: DITA-OT Cloud supports toolkit versions 2.5.4 through 3.7.4.	Don't use DITA-OT versions 2.5.4 to 3.6. They lack parameters that help with processing speed.	Minor
Toolkit size	Keep your toolkits small. The larger a toolkit, the longer publishing time. Toolkits larger than 500 MB don't upload to the CCMS. For comparison, default toolkits are typically not larger than 30-50 MB.	Do not create large toolkits that contain unnecessary resources.	Critical
Custom toolkits	Create one toolkit for each output type. For example, create one toolkit for PDF output and a separate toolkit for HTML outputs. There is no limit on the number of toolkits you can upload. This is especially important if you use Antenna House or Oxygen WebHelp.	Don't create one toolkit for all output types. Don't create a toolkit that includes both Antenna House formatter and Oxygen WebHelp plugins.	Critical
Custom plugins	Add only the custom plugins a publishing scenario needs. For example, a toolkit for PDF outputs should only contain custom plugins related to PDF outputs.	Don't add unrelated custom plugins to a toolkit. For example, a toolkit for PDF outputs should not contain custom HTML plugins.	Major
Custom fonts	Add only the custom fonts a publishing scenario needs. For example, if you use serif fonts for PDF outputs and sans-serif fonts for HTML outputs, only add the relevant font types to each toolkit.	Don't add all custom fonts to all toolkits.	Minor
Publishing scenarios	Create one publishing scenario for each output type. For example, create one publishing scenario for PDF outputs and another for HTML outputs. Each scenario should point to an output-specific toolkit that contains only output-specific custom plugins and fonts. For example, a publishing scenario for PDF outputs should point to a PDF-specific toolkit that contains only PDF-specific custom plugins and fonts.	Don't create one publishing scenario for multiple output types.	Critical
Antenna House	Only include Antenna Housein toolkits configured for PDF output generation.	Don't add to toolkits configured for HTML output and other non-PDF outputs.	Major

A sophisticated publishing configuration typically combines custom plugins and fonts, uses Antenna House, accounts for localization needs, and supports publishing to multiple output types. The more sophisticated your publishing needs, the more likely it is that your toolkit is large. This affects publishing time and we recommend following these guidelines as much as possible.

If you have optimized your toolkits and publishing scenarios and still need more publishing power, consider purchasing more DITA-OT Cloud workers for concurrent publishing. The number of workers you have by default depends on your Heretto CCMS license type. For details, contact your Customer Success Manager.

Download a Default DITA Open Toolkit

To customize a DITA Open Toolkit (DITA-OT), you need to download a default DITA-OT that you can then modify.

DITA-OT Cloud supports toolkit versions 2.5.4 through 3.7.4.

In your web browser, go to the DITA Open Toolkit web site https://www.dita-ot.org.
In the DITA Open Toolkit site, in the top menu, click Download.
Click the desired DITA-OT version, for example 3.5.4.
From the Assets list, click the asset that follows this naming convention: dita-ot-digit.digit.digit.zip.
dita-ot-3.5.4.zip

Tip:
Typically, the DITA-OT ZIP file is the first asset on the list.

Figure 1. DITA-OT Assets List

You downloaded a DITA Open Toolkit to your computer.

Add Custom Plugins to DITA Open Toolkit

Custom plugins may include transformation (publishing) customizations, document type specializations, or both. In this procedure, we are assuming that your custom plugin(s) are ready to be added to a DITA Open Toolkit (DITA-OT). For DITA-OT Cloud publishing, all custom DITA-OT plugins needed to publish with a specific publishing scenario must be included in your toolkit.

This document doesn't explain how to create custom plugins. If you do not have the skills required to prepare a custom plugin, you can learn at dita-ot.org. Alternately, we can recommend a partner who provides DITA-OT customization services.

Unzip the toolkit you want to customize.
In the unzipped toolkit, navigate to the plugins folder.
Copy any custom plugins into that folder.
Figure 2. Example DITA-OT Plugins Folder

Add Antenna House Formatter to DITA Open Toolkit

Each default DITA Open Toolkit (DITA-OT) comes with a default Formatting Objects Processor (FOP) that converts content into the PDF output format. Antenna House (AH) Formatter is an optional, custom, licensed formatter that is useful if you have complex pagination and page layout, publish PDF outputs to multiple languages, need to use fonts other than TTF, or need to specify different fonts for different locales.

Antenna House Formatter is licensed software. If you need a license, contact your Customer Success Manager.

Important:

You need to use a Linux version of Antenna House. Other versions do not work with Heretto CCMS.

Unzip the toolkit you want to customize.
In the unzipped toolkit, navigate to the root of the toolkit folder.
The root of a toolkit folder is, for example, dita-ot-3.6.1.
Create a new folder called ah-formatter.

Important:
Ensure that the folder name ah-formatter is only lower case.
Add the Antenna House components into the ah-formatter folder.
Antenna House components include a number of folders, for example, bin, docs, etc, and files, for example, ReadMe.txt, run.sh.
Important:
Do not nest additional folders such as /usr. Put only the actual components in the ah-formatter folder.
Add the Antenna House license file, AHFormatter.lic, to the ah-formatter/etc folder.
Add all custom font files to the ah-formatter/fonts folder.
The supported font formats are: TTF, TTC, OTF, AFM, PFB. Antenna House does not support WOFF.

In your DITA-OT plugins, be sure to change any references to custom font files to use the new location in your toolkit directory.

Add Custom Fonts to DITA Open Toolkit

Important:

Follow this procedure only if you use the Formatting Objects Processor (FOP) in your toolkit. If you use both an FOP and Antenna House (AH) or if you use Antenna House only, add custom fonts inside the Antenna House folder instead. See Add Antenna House Formatter to DITA Open Toolkit.

Fonts in a DITA Open Toolkit (DITA-OT) are available only to that toolkit and the related publishing scenario. If you have multiple toolkits that need to use the same fonts, you need to add those fonts to each toolkit.

For PDF publishing, by default, DITA-OT supports fonts in the TTF format only. If you use other font formats, use the Antenna House formatter.

Unzip the toolkit you want to customize.
In the unzipped toolkit, navigate to the root of the toolkit folder.

The root of a toolkit folder is, for example, dita-ot-3.6.1.
Create a new folder called custom-fonts.

Important:
Ensure that the folder name custom-fonts is only lower case.
Add font files to the custom-fonts folder.

Figure 3. The dita-ot-3.6.1 Root Folder with a custom-fonts Folder

In your DITA-OT plugins, be sure to change any references to custom font files to use the new location in your toolkit directory.

Compress the Custom DITA Open Toolkit into a ZIP File

Your custom DITA Open Toolkit (DITA-OT) needs to be compressed into a ZIP file. Before compressing the toolkit, give it a meaningful name. We recommend adding _embed, the date of toolkit creation, or both to the folder name. All toolkits you upload to Heretto CCMS need to have unique names.

Give your toolkit folder a meaningful name.
Consider providing the following information in the toolkit name:
- The full toolkit name, for example, dita-ot-2.5.4.
- The date of when the toolkit was created or added to Heretto CCMS. For example, dita-ot-2.5.4-aug-10-2022.
- The word embedded or something similar to indicate that the toolkit contains custom plugins. For example, dita-ot-2.5.4-emb-aug-10-2022.
Compress your folder into a ZIP format.

Add a DITA Open Toolkit to Heretto CCMS

Upload your custom DITA Open Toolkit (DITA-OT) ZIP file to Heretto CCMS so you can use it in publishing scenarios.

To complete this procedure, you need to be an Administrator in Heretto CCMS.

In the top-left corner, click the Main Menu and go to DITA-OT.
In the Toolkits section, click New toolkit.
In the New Toolkit window, in the Toolkit name field, provide a name for the toolkit.
Tip:
To use the ZIP file name as the toolkit name, leave the Toolkit name field empty.

Consider providing the following information in the toolkit name:
- The full toolkit name, for example, dita-ot-2.5.4.
- The date of when the toolkit was created or added to Heretto CCMS. For example, dita-ot-2.5.4-aug-10-2022.
- The word embedded or something similar to indicate that the toolkit contains custom plugins. For example, dita-ot-2.5.4-emb-aug-10-2022.
Click Choose file and select the DITA-OT ZIP package.
Click Create.

Note:
Depending on its size and your internet connection, uploading a new toolkit may take a few minutes.

Once the upload completes, the new toolkit is listed in the Toolkits section.

Create a publishing scenario with the DITA-OT that you uploaded. See Create a DITA-OT Publishing Scenario in Heretto CCMS.

Gretyl's Portal

Heretto Help