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
markdownformat 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
mditaformat 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.
| Features | Markdown DITA | MDITA (LwDITA) |
|---|---|---|
DITA map @format attribute | markdown or md | mdita |
| LwDITA | – | ✔ |
| First ¶ | Body ¶ | Short description |
| Subheadings | Nested topics | Sections |
| Topic IDs | Special attributes or title | Generated from title |
| Output class | Special attributes block | – |
| Profiling atts | Special attributes block | – |
| Topic types | Special attributes block | – |
| Schemas | YAML frontmatter | – |
| Tables | OASIS exchange table model 1 | DITA <simpletable> |
| Cell alignment | ✔ | – |
| Sections | Defined via attributes | – |
| Examples | Defined via attributes | – |
| Notes | MkDocs Material admonitions | – |
| Markdown maps | Map schema | .mditamap extension |
| Maps: topic sequences | OL in Markdown map | – |
| Maps: key definitions | Link reference definition | – |
| Maps: reltables | MultiMarkdown tables with links | – |
| Key references in topics | ✔ Shortcut reference links | ✔ Shortcut reference links |
| List spacing | loose or tight (no blank lines) | loose only (¶ per item) |