DITA XML vs Markdown Syntax and Capabilities Comparison
The following article is a comparison between the DITA XML standard and Markdown. The comparison attempts to cover syntax specification and features. I attempted to write this comparison without any implicit bias towards one or the other, if there are DITA XML or Markdown features that I missed, that was done out of ignorance and not out of malice. Feedback is always welcomed as usual.
DITA XML | Markdown | |
---|---|---|
Short description | DITA XML is a standard for designing, writing, managing, and publishing information. There are multiple versions of the DITA standard, the most popular one being version 1.3. | Markdown is a lightweight markup language that you can use to add formatting elements to plain text documents. There was an effort to standardize Markdown to a specification named CommonMark. In the wild there are lots of Markdown flavors and extensions most of them sharing a common set of features. The most popular are probably CommonMark and Github Flavored Markdown. |
Useful links for learning | Resources for learning DITA with Oxygen | |
Pros |
|
|
Cons |
|
|
Cross-Compatibility | A DITA Map can refer to a Github flavored Markdown file and the publishing engine can perform dynamic conversion from Markdown to DITA while editing. | - |
Table of contents | Gathering multiple DITA topics in a larger publication and defining the table of contents is done by using DITA Maps. | CommonMark does not define the possibility to
create a table of contents or to aggregate multiple Markdown files in
larger publications. Various static web site generators have various ways to define table of contents, usually based on Yaml like MKDocs. |
Validation |
|
|
Publishing |
|
Most publishing libraries rely on the conversion from
Markdown to HTML.
|
Translation | There are translation agencies accepting directly DITA
XML content or you can convert DITA XML to XLiff and use a translation
system. Each DITA XML topic or map can have an @xml:lang
attribute to specify the current language in which it is
written. |
There are various tools like Simpleen which seem to specifically handle Markdown translation. |
Extensibility |
|
|
Metadata |
|
|
Content reuse: |
|
No content reuse support is in the standard base, various extensions do exist for example: |
Filters | You can use profiling attributes in DITA
XML topics or on topic references in a DITA Map map. By using a single
DITA Map and filtering it differently you can obtain multiple
publications from it. For example for the Oxygen user's manual we obtain from the same DITA Map lots of distinct publications for "Oxygen XML Editor", "Oxygen XML Author", "Oxygen XML Web Author". |
There may be but I am not aware of such a feature in Markdown. |
Headings |
|
You can use a number of # followed by
space and text to define a new heading. Headings
do not necessarily need to be incremental, you can start with heading
level 2 and then have a heading level
1.
|
Block elements | There are multiple topic types like
<concept> , <task> ,
<reference> and extra topic types can be
added using specialization. The basic block elements are
<topic> , <title> ,
paragraph <p> elements,
<codeblock> , lists
<ul>
<ol> , <table> ,
<section> , <fig> ,
<image> , <note> . There
are also other block level elements depending on the topic type. |
Block elements: Paragraphs, tables, lists, images, block quotes, etc. |
Inline elements | <b> , <i> ,
<u> ,<sup> ,<sub>
and other inline elements with more semantic meaning like
<codeph> , <uicontrol> ,
<filepath> . |
Bold, italic,underline. Depending on the Markdown flavor also other inlines like subscript, superscript, strike-through. |
Audio/Video | The DITA <object> element can be
used to refer to audio, video or iframe
content. |
No official support, maybe use embedded HTML content or add a link to the audio/video instead. |
Tables | The DITA <table> element is based
on the CALS table specification. Cells can span multiple rows or columns
and contain inside block elements content like lists, paragraphs. The table can have header and
body rows. |
Markdown tables are usually written in an ASCII graphic like representation allowing for cells content to be aligned left or right. By default cells can contain inside only plain text. If more complex table structures are needed, HTML tables can be inserted directly in Markdown if the used Markdown flavor supports HTML elements inside it. |
Lists | Ordered <ol> , unordered
<ul> or definition lists
<dl> . Other topic types like
<task> contain for example the
<steps> element which is an ordered list of
steps. Each list item can contain inside block elements like paragraphs,
other lists, tables, etc. |
Ordered and unordered lists.
Each list element contains inside simple content, it cannot contain
block level elements like additional lists or multiple paragraphs. The task list is an interesting extension to show checkboxes next to each list item. Other types of lists (definition list for example) or list items containing multiple block level elements can be inserted directly in Markdown if the used Markdown flavor supports HTML elements inside it. |
Links |
|
Links to other web resources. |
Conclusion |
|
|