Edit online

Working with Markdown Documents in DITA

The Oxygen XML Author Eclipse plugin has special features that make it easy to incorporate Markdown documents into a DITA project. This is particularly useful for teams with members who are familiar with Markdown syntax but want to generate their output from DITA projects. The integration between the Markdown editor and DITA includes options to export or convert Markdown documents into DITA topics, as well as a live preview of the edited Markdown content.

Preview

The changes made to the Markdown content can be previewed live in three separate tabs: DITA, XDITA, and HTML.

The DITA tab in the Preview pane shows how an equivalent DITA topic will look after conversion. Similarly, the XDITA tab shows how a Lightweight DITA topic will look after conversion. The HTML tab shows a previous of the HTML equivalent.

Keys that are defined in the root map are also resolved in the Preview pane in the XDITA and DITA tabs.

Note:

To make the content generated for preview in the DITA and XDITA preview tabs more readable and to improve the conversion of Markdown to DITA in the editor, you can add an XML catalog to the XML catalogs list. This XML catalog will help with post-processing before the content is displayed. Here is an example of an XML catalog that you can use:

<catalog 
  xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <uri 
  name="http://www.oxygenxml.com/ns/preview/postprocess/dita" uri="postProcessDITA.xsl"/>
  <uri 
  name="http://www.oxygenxml.com/ns/preview/postprocess/lwdita" uri="postProcessLWDITA.xsl"/>
</catalog>

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.

Working with Markdown Documents in the DITA Maps Manager

Oxygen XML Author Eclipse plugin has some specialized features that allow you to integrate Markdown documents directly into your DITA project using the DITA Maps Manager. The following features are available for Markdown documents in the DITA Maps Manager view:
  • Insert Reference to Markdown Document - You can use the New, Reference, and Reference to the currently edited file actions from the Append Child, Insert Before, or Insert After submenu when invoking the contextual menu in the DITA Maps Manager to insert a reference to a Markdown document at the selected location in the map. Markdown documents will be inserted as a topic reference (topicref element) with the format attribute set to markdown.
  • Validate Markdown Documents in DITA Maps - When you use the Validate and Check for Completeness action from the DITA Maps Manager toolbar to check the integrity of the structure of a DITA map, Markdown documents that are referenced in the DITA map will be converted to DITA topics in the background and validated the same as any other DITA topic.
  • Transforming DITA Maps with Markdown Documents - When transforming DITA maps that have Markdown documents referenced, the transformation will convert the Markdown documents to normal DITA output without you needing to manually convert the Markdown documents to DITA topics.

  • Manually Convert Markdown Documents to DITA Topics - If you need to use DITA semantics that are not possible in Markdown syntax (such as content references, related links, and other DITA-specific syntax), you can manually convert the Markdown document into a DITA topic. To do so, right-click the Markdown document in the DITA Maps Manager and select Refactoring > Convert Markdown to DITA Topic. This will open a dialog box that allows you to configure options for converting the document to an XML file that is defined as a DITA topic.

    Figure 1. Convert Markdown to DITA Topic Dialog Box

    This dialog box includes the following options:

    Destination
    The destination path for the new DITA topic.
    File Name
    Presents the current name and allows you to change it.
    Update references
    Select this option to update all references of the file in the DITA map and in the files referenced from the DITA map.
    Delete Markdown file
    If selected, the Markdown version of the file is deleted when the document is converted into a DITA file. If deselected (default value), when the document is converted into a DITA file, the original Markdown file is also preserved in its current location.
    Preview
    Select this button to display a preview of the changes Oxygen XML Author Eclipse plugin is about to make.
    Convert
    Select this button to perform the conversion. If the Markdown file has format="markdown", it will be converted to a DITA topic. If it has format="mdita", it will be converted to a LightWeight DITA topic.
Tip: Oxygen XML Author Eclipse plugin comes with a sample ditamap project for converting Markdown to DITA. Go to the Project Explorer view, open the sample.xpr project, and navigate to the dita/markdown-dita folder.

DITA-Related Markdown Syntax

For a list of Markdown rules and syntax examples that are specific to DITA, see the Markdown DITA Syntax Reference.