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.

These output formats can be used to feed DITA content into Markdown-based publishing systems, static site generators, 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 format.

    Markdown DITA output includes a table of contents file based on the topic hierarchy in the root map. The index.md file links to each topic in a bulleted list with Markdown link syntax: [link](destination).

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

    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 format.

    Since GitBook includes built-in navigation for previous and next topics, the default settings for this format do not include child links in topic content. If you need related links, set args.rellinks to the desired link roles.

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.