DITA XML vs Markdown Syntax and Capabilities Comparison

• You work (or want to work) for a company which manufactures similar products (large possibility of content reuse).
• You want to obtain multiple output formats (HTML based, quality PDF).
• You want to work with a standard and be able to change tools if necessary.
• You want to impose structural validation constraints on the edited content.

• You work for a company which has mostly one product and publishes the documentation mostly on the web.
• You work with ticketing systems which use Markdown for styling content.
• You produce internal documentation or small articles.

• Basic Markdown Syntax
• Markdown: Syntax

DITA XML pros and cons

• OASIS Open standard.
• Advanced support for content reuse either at topic, block, or inline level.
• Advanced support for filtering (generating multiple similar user guides from the same content).
• Open-source publishing engine with lots of supported output formats (some free, some commercial) like HTML5, Windows Help, PDF, Word, EPUB, and so on.

Why use DITA

Pros and Cons

Markdown pros and cons.

• Large user base. Familiar to software engineers who use it to write issues.
• Basic syntax, easy to learn.
• Easier to read without specialized tools.
• Offline and online free editing tools.
• For the base syntax, quite easy to edit the content in a plain text editor tool.
• Lots of static web site generator open-source tools like MKDocs or Jekyll.

• Smaller user base.
• Harder to learn.
• XML is more verbose than plain text.
• Visual editing requires the use of a commercial tool like Oxygen.
• Smaller number of open source tools to generate professional looking outputs.

• Not all language features are available in the base Markdown "specification". There are various flavors with various syntax differences between them and you probably need to pick a flavor to use and stick to it.
• Advanced features like content reuse, for example, are not in the base standard but may be implemented with different syntaxes for various flavors.
• Static web site generators are not compatible with each other (they have various specific configuration files) or to link between files.
• Not many possibilities to assemble multiple Markdown files and publish outputs like PDF or Word, for example.
• Cannot render complex cell content (multiple paragraphs, for example) in table cells or in list items.

Working with DITA Maps

Various static web site generators have various ways to define table of contents, usually based on Yaml, like MKDocs.

• Validation according to the DITA specification DTDs/schemas done when publishing or when editing.
• Additional validation can be done with Schematron rules.

• Usually with Markdown, you can look at a live preview while typing to see that everything looks OK.
• There are various processors that may be used to validate Markdown, for example using a set of JSON rules.

• The DITA Open toolkit publishing engine comes with default support to publish DITA Maps and customize to plain HTML5, PDF.
• There are additional open-source plugins to publish to MS Word or EPUB.
• Other curated open-source plugins are available in the DITA OT plugins registry.
• Commercial plugins are available to publish to WebHelp output like Oxygen WebHelp or Fluid Topics.

• Lots of open-source static web site generators.
• Lots of libraries (Javascript, Java, Python, etc) to convert Markdown to HTML.
• Other conversion types available using Pandoc.

Translating your DITA Project

• Possibility to define a new specialization of the DITA vocabulary with new element names.
• Use the @outputclass attribute value on elements to set custom values used when styling the output.
• Use the DITA <data> element with custom names and values and take them into account with publishing time customizations.
• Use the DITA <foreign> element (for example, embed HTML inside it using a custom publishing plugin).

• Use HTML elements inside Markdown, for example, when defining complex tables or you do not have a Markdown equivalent.
• Yaml headers.
• Ability on certain Markdown flavors/extensions to define attributes for each element.

• The DITA <prolog> element can contain lots of metadata information, but not visible in the published output. Example:

  <topic id="topic_wcj_tgy_5wb">
   <title>The Title</title>
   <prolog>
    <author>The Author</author>
    <metadata>
      <keywords>
  	<keyword>one</keyword>
         <keyword>two</keyword>
      </keywords>
     </metadata>
    </prolog>

• The <indexterm> elements are also considered metadata, as they are used to generate an index table.

• Sometimes, Markdown files may contain Yaml headers before the actual content that define simple keys and values. Example:

  ---
  title: The Title
  author: The Author
  keywords: [one, two, three, four]
  ---
  # A Heading
  Text body. 

• Key references to re-used product names.
• Content references to re-used elements in multiple places.
• Content reference push to push content in multiple places.
• Code references to re-use pieces of code in multiple places.
• Key scopes and branch filtering to re-use the same topics in multiple contexts with different content in each context.
• Re-use a topic in multiple places in the publication.

• Redocly uses HTML <embed> tags with references to Markdown files to re-use entire chunks of Markdown content placed inside a file.
• Hugo uses special notations named shortcuts.

For example, for the Oxygen user's manual, we obtain lots of distinct publications for "Oxygen XML Editor", "Oxygen XML Author", "Oxygen XML Web Author" from the same DITA Map.

• DITA topics have a <title> element that appears as a heading 1 when published and is also used for the <title > element in the published HTML document.
• You can nest topics one inside the other and the generated HTML output will have <h2>, <h3>, etc for each nested topic, depending on the nested depth.
• You can have <section> elements with <title>elements inside a topic (they cannot be nested one inside the other).

  <topic id="topic_wcj_tgy_5wb">
   <title>Title1</title>
   <body>
    <section>
      <title>Section 1</title>
      <p>paragraph</p>
    </section>
   </body>
   <topic id="inner">
    <title>Inner topic title</title>
   </topic>
  </topic>

# Heading level 1
### Heading level 3
## Heading level 2
....

• MathML equations added directly inside the DITA topics or referenced as separate files.
• Latex equations embedded using third party plugins in DITA <foreign> elements.

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 that contain multiple block-level elements can be inserted directly in Markdown if the used Markdown flavor supports HTML elements inside it.

• Internal links (cross references):
  • Link to another topic.
  • Link to a particular element in another topic.
  • Links to web resources.
• Related links (at the end of each topic)
  • Link to another topic.
  • Link to a particular element in another topic.
  • Links to web resources.

• Harder to type in a plain text area, requires DITA editing tools (most of which, are not free).
• Advanced support for structured validation.
• Advanced support for content re-use and profiling conditional text.
• Publishing engine allows publishing to multiple output formats like HTML, PDF, and others based on plugins that can be installed.

• Easy to manually type in a plain text area but a preview definitely helps.
• More complex elements need to be inserted as HTML elements.
• Various Markdown extensions have extra support for example for content reuse.
• Mostly targeted towards obtaining web-based HTML content.
• Looks like a language that is not intended to do the heavy lifting of producing multiple deliverable formats and deliverables from the same content.