Generating Markdown output

Along with Markdown input, DITA-OT provides three transformation types to convert DITA content to Markdown, including the original syntax, GitHub-Flavored Markdown, and GitBook.

The new output formats can be used to feed DITA content into Markdown-based publishing systems or other workflows that lack the ability to process DITA XML.

Markdown output can be generated by passing one of the following transformation types to the dita command with the --format option:

  • To publish Markdown DITA files, use the markdown transtype.

  • To generate GitHub-Flavored Markdown files, use the markdown_github transtype.

    Note:
    Since the GitHub format does not support definition lists, they are converted to unordered lists with bold terms. Attribute blocks with IDs, class names, and other custom attributes are also omitted, as GitHub does not support Pandoc header attributes or PHP Markdown Extra special attributes.

  • To publish GitHub-Flavored Markdown and generate a SUMMARY.md table of contents file for publication via GitBook or mdBook, use the markdown_gitbook transtype.

Run the dita command and set the value of the output --format option to the desired format, for example:

dita --input=input-file --format=markdown

where:

  • input-file is the DITA map or DITA file that you want to process.
Attention:
The MDITA format is not yet supported when generating output. To publish DITA content to Markdown, use one of the formats listed above.