Dynamic Word, Excel, OpenAPI, HTML, Markdown to DITA Conversion

The publishing engine has support to dynamically convert various types of non-DITA resources to DITA while publishing. This support also enables the dynamically converted document titles for the non-DITA resources that are referenced in a DITA map to be displayed as the title of the resource in the DITA Maps Manager.

Attention: These features are available with no restrictions when the publishing process is done using the default publishing engine that is bundled in Oxygen XML Editor/Author or if you have integrated the DITA-OT dynamic converter plugin into a custom DITA-OT distribution. However, if the publishing process is done from a command line, this feature requires an Oxygen Publishing Engine license.

To enable this support for a particular resource that is referenced in a DITA map, you must specify one of the following values for the @format attribute on the <topicref> element:

Word to DITA (word-to-dita)

Microsoft Word documents that are referenced in the DITA map using the word-to-dita value for the @format attribute get dynamically converted to DITA topics during publishing. Image references and internal links are preserved.

Example:

<topicref href="sample.docx" format="word-to-dita"/>

Excel to DITA (excel-to-dita)

Microsoft Excel documents that are referenced in the DITA map using the excel-to-dita value for the @format attribute get dynamically converted to DITA topics that contain one or more tables during publishing.

Example:

<topicref href="sample.xlsx" format="excel-to-dita"/>

OpenAPI to DITA (openapi-to-dita)

OpenAPI documents (versions 2.0, 3.0, or 3.1) in JSON or YAML format that are referenced in the DITA map using the openapi-to-dita value for the @format attribute get dynamically converted to DITA topics during publishing.

Example:

<topicref href="openapi.json" format="openapi-to-dita"/>
<topicref href="openapi.yaml" format="openapi-to-dita"/>

HTML to DITA (html-to-dita)

HTML documents that are referenced in the DITA map using the html-to-dita value for the @format attribute get dynamically converted to DITA topics during publishing.

Example:

<topicref href="sample.html" format="html-to-dita"/>

Markdown to DITA (markdown)

Markdown documents that are referenced in the DITA map using the markdown value for the @format attribute get dynamically converted to DITA topics during publishing using the support for Markdown bundled with the publishing engine by default.

Example:

<topicref href="sample.md" format="markdown"/>

Markdown to DITA (markdown-to-dita)

Markdown documents that are referenced in the DITA map using the markdown-to-dita value for the @format attribute get dynamically converted to DITA topics during publishing using the special conversion plugin provided by Oxygen XML Author Eclipse plugin. The markdown-to-dita format conversion is more flexible that the built-in markdown conversion, allowing the conversion of Markdown documents that do not have consistent heading levels.

Example:

<topicref href="sample.md" format="markdown-to-dita"/>

Resources

For more information about working with DITA-compatible resources, see the following resources: