Configuring DITA Open Toolkit Output Formats


Prerequisites: Before setting DITA output formats, install the DITA-OT in DITA Setup. See Installing DITA Open Toolkit for details.

Ingeniux CMS publishes DITA source to various output formats with the installed DITA-OT. The DITA-OT uses a plugin-based architecture, so output formats are generated by installing output-specific plugins.

When Ingeniux CMS publishes to the DSS, it uses normalization to pre-process DITA content on its way through the Ingeniux CMS publishing pipeline. Normalization resolves map references, keys, content references, etc. Normalized DITA is an intermediate, DITA-to-DITA transform—not the final information product.

In addition to normalized DITA, the DITA-OT can output other formats such as PDF, HTML5, XHTML, and Markdown. These output types do not undergo further transformations by Ingeniux CMS, so they are referred to as static output formats.

To configure DITA output formats:
  1. Navigate to Administration > DITA > Output Formats.
  2. Select the Normalization Output Format header bar to the area.
    The Normalization Output Format area allows you to set the DITA-OT's plugin used for normalization, to assign a friendly name for easy identification throughout the CMS, and to set a CMS page schema that will contain the final DITA output when you publish to your DSS website.
  3. In the Normalization Output Format String field, take one of the following actions based on your installed DITA-OT:

    Select Normalization Output Form String Drop-Down Arrow

    • If you installed a Ingeniux's DITA-OT version or a version of the DITA-OT's community edition in the Setup view and have not uploaded a custom normalization plugin, select the field's drop-down arrow and choose the provided default option (i.e., dita [org.dita.normalize - Normalized DITA].
    • If you uploaded a custom normalization plugin, then select field's drop-down arrow and choose your custom normalization plugin from the list.
      Important
      Normalization transtype name values for custom plugins require the term normalize or normalization in order to display as a normalization output format choice. If your custom normalization plugin does not display in this field, ensure its plugin.xml conforms to this naming convention. For example:
      <plugin id="org.dita.normalize">
          <transtype name="normalize" desc="Custom DITA normalization plugin"/>
          <feature extension="dita.conductor.target.relative" file="conductor.xml"/>
      </plugin>
    • If you will not publish normalized DITA as a pre-processing step for delivery to your DSS website, then leave Normalization Output Format String field value empty.
    Note
    If you upload a custom normalization plugin at a later time, then return to this field and select the option from the list.
    After entering a Normalization Output Format String value, the Normalization Output Format and Rendering Schema for DSS fields display.

    Normalization Output Format Fields

  4. In the Normalization Output Format Display Name field, enter an easily identifiable name for the normalization output format.
    The field contains a default name (e.g., Normalization Output for Web Rendering), but you may want to change the name to one more suitable to your organization.
  5. In the Rendering Schema for DSS field, enter the display name of a page schema that will contain the final output rendered to your DSS website.
    Note
    Ingeniux CMS provides a basic, default page schema, DITA Detail, for this purpose. A default schema can be further developed and renamed to meet the needs of your organization.
  6. Navigate to the Static Output Formats list of core output formats for DITA publishing.

    Static Output Formats

    Default DITA-OT PluginDescription

    html5 (org.dita.html5 - HTML5)

    The html5 transformation generates HTML5 output and a table of contents (TOC) file.

    markdown (org.lwdita - Markdown)

    Publishes DITA to Markdown files. Uses the markdown transtype.

    markdown_gitbook (org.lwdita - GitBook)

    Publishes GitHub-flavored Markdown and generates a SUMMARY.md table of contents file for publication via GitBook or mdBook. Uses the markdown_gitbook transtype.

    markdown_github (org.lwdita - GitHub-flavored Markdown)

    Markdown supported for user content on GitHub and GitHub Enterprise. Uses the markdown_github transtype.

    pdf (org.dita.pdf2 - PDF)

    Generates output in Portable Document Format (PDF). This is the original IBM PDF transformation. Uses the pdf transtype.
    Note
    Unless your organization has a specific need for this output, use pdf2 instead.

    pdf2 (org.dita.pdf2 - PDF2)

    Generates output in Portable Document Format (PDF). Uses the pdf2 transtype.

    xhtml (org.dita.xhtml - XHTML)

    The xhtml transformation generates XHTML output and a table of contents (TOC) file. This was the first transformation created for DITA Open Toolkit, and originally served as the basis for all HTML-based transformations.

  7. Select any static output formats (e.g., HTML5, markdown, PDF, XHTML, etc.) that your organization requires.
    Note
    When you configure publishing targets that include DITA output, you may not require all of the output formats that you set here. The output formats that you define here display as output options for each publishing target's DITA post-publish content processor in the Publishing System. You can enable or disable any of the output formats you have chosen as needed in the post-publish content processor.
    For details about these static output formats, see DITA-OT transformations (output formats).
  8. Optional: In the Display Name field, enter an easily identifiable name for any static output formats you've selected.
    These fields contain a default name, but you may want to change them to friendlier ones.

Next Steps (optional): Configure DITA-OT parameters that Ingeniux CMS will use during the post-publishing process to generate DITA output formats.