Handling HTML Embedding in DITA - Fluid Topics

A specification for structured technical documentation like DITA uses a content model governed by an XML schema. This schema defines the elements, their order, and the rules relating to their attributes and content. To ensure document validity, two types of XML schemas are commonly used: DTDs and RNGs, acting as guides for authors and XML processing tools.

In specific contexts, incorporating HTML into DITA content may prove essential; this need may arise during rapid prototyping, for instance. Additionally, integration of excerpts from third-party sources may require direct inclusion of HTML code. Examples of such instances include embedding multimedia content via iframes or integrating HTML code snippets sourced from external websites.

This document thus presents two solutions based on DITA-OT plugins that can meet this need.

To insert HTML snippets into DITA topics, there are two available solutions:

• Utilize the Oxygen plugin dita-embed-html-xslfo. This plugin facilitates the embedding of well-formed HTML content within a DITA topic by employing a dedicated element.

• Alternatively, consider to use the custom plugin release for internal use: com.antidot.generic

dita-embed-html-xslfo is compatible with both DITA OT 2.x and 3.x. To utilize this plugin, download it and install it into the plugins folder. Then, proceed to execute the integrator of DITA-OT.

Original source

<foreign outputclass="html-embed">
    <![CDATA[
            <iframe width="420" height="315" src="https://www.youtube.com/embed/qepRkQxhTXQ" frameborder="0" allowfullscreen="true">
            </iframe>
    ]]></foreign>

Note the use of the <![CDATA[ ... ]]> tag in XML, which encapsulates sections of text data interpreted literally by the XML processor. This tag allows inclusion of raw content like HTML or scripts without XML processing, preserving the original content's structure and meaning.

Conversion to HTML

The original YouTube-provided code consists of an iframe element with attributes such as width, height, and src. Here is the rendered output:

  <iframe width="420" height="315" src="https://www.youtube.com/embed/qepRkQxhTXQ" frameborder="0" allowfullscreen="true">
  </iframe>

This custom plugin is available as an attachment. It serves the same purpose as the previous one, but it does not require the <![CDATA[ ... ]]> tag and make its use less verbose and more semantically explicit.

Content using this element can take this form:

<generic>
      <iframe width="420" height="315" src="https://www.youtube-nocookie.com/embed/99CINevsGbA"/>
</generic>

Apart from integrating the plugin, the only constraint with this plugin arises if a client has custom DTDs or RNGs with custom elements. In such cases, it's essential to update the custom DTDs to include the <generic> element.

Both the dita-embed-html-xslfo and com.antidot.generic plugins provide viable solutions for embedding HTML snippets into DITA topics. However, each approach has its own advantages and considerations:

In general, prefer the dita-embed-html-xslfo plugin for its official support and compatibility, especially in projects with strict validation requirements. However, the com.antidot.generic plugin is a more convenient choice for simpler use cases or when working with custom schemas that can be easily updated.