Edit online

DITA to Confluence

Radu Coravu
27 Feb 2020
Read time: 4 minute(s)

Atlassian Confluence is a content collaboration tool used to help teams collaborate and share knowledge efficiently. Based on my limited knowledge of Confluence, I've identified several ways that you can write technical documentation in DITA and then make it available on the Confluence platform:

Publish DITA to Microsoft Word and import in Confluence

Oxygen XML Editor comes bundled with support to publish DITA content to Microsoft Word using the DITA to Word plugin: https://www.oxygenxml.com/doc/ug-editor/topics/ditamap-ms-word.html.

Once you publish the DITA project to Word, you can use the Import Word Document action in Confluence to import the Word document.

During the import process, you will be able to choose to split the document into multiple pages depending on the headings.

Publish DITA to HTML5 and import in Confluence

Although Confluence supports out-of-the-box importing only from Microsoft Word, there is a commercial file importer plugin for Confluence: https://marketplace.atlassian.com/apps/1221333/all-in-one-file-importer-for-confluence. This plugin can import various file formats to Confluence, including Markdown and HTML.

The plugin contributes an import action that can be used to either import individual HTML or Markdown files or entire folders. The plugin might try to import various unwanted file formats (such as CSS and image files) so these types of files need to be manually deleted before the import process. Also, the plugin does not seem to properly resolve links between the imported HTML files.

Publish DITA to HTML5 and paste from Web Browser to Confluence

If you just want to update a few pages, you can publish DITA to HTML, open the published HTML content in a web browser, select and copy the contents, then paste in a Confluence page. Confluence seems capable of converting the pasted HTML content to its own HTML-like format. Some manual cleanup may be required after pasting the content.

Creating a special DITA to Confluence-like HTML publishing flow

The internal storage format Confluence uses is a kind of HTML mixed with XML content: https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html.

If a DITA OT plugin were to implement special DITA to Confluence-like HTML output, it would probably need special handling for:
  • Internal links.
  • Links to binary resources.
  • Images.