Working with Markdown Documents in DITA
Edit online

Oxygen XML Developer includes some unique features that allow you to easily integrate Markdown documents in a DITA project. This is especially helpful for teams that have contributors who are familiar with the Markdown syntax, but they want their output to be generated from DITA projects. The integration between the Markdown editor and DITA includes actions to export or convert Markdown documents to DITA topics and the DITA tab in the Preview pane provides a visualization of how the topic will look after conversion.

Export Markdown as a DITA Topic

The Markdown editor includes an option to quickly convert the current Markdown document into a DITA topic. The Export as DITA Topic action is available in the contextual menu.

The conversion creates a new XML file that is defined as a DITA topic and opens it in the Text editing mode. You can then work with the document as you would with any other DITA topic, although you may need to manually correct some issues where the parser could not properly map Markdown syntax to DITA markup.

Tip: Oxygen XML Developer comes with a sample ditamap project for converting Markdown to DITA. Go to the Project view, open the sample.xpr project, and navigate to the dita/markdown-dita folder.

Converting Markdown to DITA Using the Lightweight DITA Standard

The bundled DITA-OT 2.x does not support converting Markdown documents to DITA using the Lightweight DITA standard specification (which is more strict than the normal Markdown to DITA format conversion), but Oxygen XML Developer provides a way to enable this support by using a special add-on.

To convert Markdown documents to Lightweight DITA topics, follow this procedure:
  1. Install the DITA OT 3.x Publishing Engine Add-on.
  2. Restart the application.
  3. Go to Options > Preferences > DITA and in the DITA Open Toolkit section, select the DITA OT 3.x option.

    Step Result: Markdown documents referenced in a DITA map can now accept the mdita format (Right-Click MD document in DITA Maps Manager > Edit Properties > Attributes tab > Select 'mdita' from drop-down menu in the Format attribute).

  4. Double-click the Markdown document in the DITA Maps Manager.

    Step Result: This will open the Markdown document in the editor and the DITA preview pane will show the conversion using the Lightweight DITA mdita format encoding rules.

  5. Right-click anywhere in the DITA preview pane (or the left-side editor) and select Export as DITA Topic.

    Step Result: The Markdown document is converted to DITA using the Lightweight DITA mdita format encoding rules.

Converting Multiple Markdown Documents to DITA

Oxygen XML Developer offers an add-on that contributes actions in the Tools menu and contextual menu to enable batch conversion between various formats, including Markdown to DITA. For more information and instructions for installing the add-on, see Batch Converter Add-on.