Format comparison

Although the original Markdown DITA format and the MDITA format for LwDITA share some common syntax, there are several differences to consider when choosing which format to use.

  • In 2015, the original DITA-OT Markdown plug-in introduced a series of conventions to convert Markdown content to DITA, and vice-versa. This Markdown flavor was called “Markdown DITA”. The markdown format adds several complementary constructs to represent DITA content in Markdown, beyond those proposed for the MDITA format in the Lightweight DITA specification drafts.

  • In 2017, the Markdown plug-in was superseded by the LwDITA plug-in, which was bundled with DITA-OT 3.0, and added new formats for Lightweight DITA. The mdita format implements the subset of Markdown features proposed in the latest specification drafts, but differs in some ways from the original Markdown DITA format.

The following table provides an overview of differences between the markdown and mdita formats.

FeaturesMarkdown DITAMDITA (LwDITA)
DITA map @format attributemarkdown or mdmdita
First ¶Body ¶Short description
SubheadingsNested topicsSections
Topic IDsSpecial attributes or titleGenerated from title
Output classSpecial attributes block
Profiling attsSpecial attributes block
Topic typesSpecial attributes block
SchemasYAML frontmatter
TablesOASIS exchange table model  1 1DITA <simpletable>
Cell alignment
SectionsDefined via attributes
ExamplesDefined via attributes
NotesMkDocs Material admonitions
Markdown mapsMap schema.mditamap extension
Maps: topic sequencesOL in Markdown map
Maps: key definitionsLink reference definition
Maps: reltablesMultiMarkdown tables with links
Key references in topics✔ Shortcut reference links✔ Shortcut reference links
List spacingloose or tight (no blank lines)loose only (¶ per item)