-
-
Notifications
You must be signed in to change notification settings - Fork 19
MDITA syntax
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.
To apply the stricter LwDITA-specific processing to a Markdown topic, create a topic reference in your map and set the @format
attribute to mdita
:
<map>
<topicref href="mdita-topic.md" format="mdita"/>
</map>
In this case, the first paragraph in the topic will be treated as a short description, and tables will be converted to DITA <simpletable>
elements.
The MDITA format uses CommonMark as the underlying markup language. MDITA files must be UTF-8 encoded.
The MDITA parser processes topics according to the MDITA “Extended profile” proposed for LwDITA. The "Core profile" can be enabled for custom parser configurations.
The following Markdown constructs are parsed differently when the @format
attribute is set to mdita
.
The first heading level will generate a topic and the second heading level a section:
# Topic title
## Section title
<topic id="topic_title">
<title>Topic title</title>
<body>
<section>
<title>Section title</title>
</section>
</body>
</topic>
The ID is generated from title contents.
The first paragraph is treated as a shortdesc
element.
# Topic title
First paragraph.
Second paragraph.
<topic id="topic_title">
<title>Topic title</title>
<shortdesc>First paragraph.</shortdesc>
<body>
<p>Second paragraph.</p>
</body>
</topic>
Tables use MultiMarkdown table extension format:
| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content | _Cell_ | Cell |
| Content | **Cell** | Cell |
MultiMarkdown tables are converted to DITA <simpletable>
elements.
Note
Cell alignment information is not preserved, as the@align
attribute is are not available for<simpletable>
elements.
<simpletable>
<sthead>
<stentry>
<p>First Header</p></stentry>
<stentry>
<p>Second Header</p></stentry>
<stentry>
<p>Third Header</p></stentry>
</sthead>
<strow>
<stentry>
<p>Content</p></stentry>
<stentry>
<p><i>Cell</i></p></stentry>
<stentry>
<p>Cell</p></stentry>
</strow>
<strow>
<stentry>
<p>Content</p></stentry>
<stentry>
<p><b>Cell</b></p></stentry>
<stentry>
<p>Cell</p></stentry>
</strow>
</simpletable>
Table cells may only contain inline content.
DITA maps can be written in MDITA using standard Markdown syntax for links and lists.
Note: Requires DITA-OT 4.1 or newer.
In MDITA, maps use the file name extension mditamap
to define the file as a map:
# Map title
- [Topic title](topic.md)
- [Nested title](nested.md)
<map>
<title>Map Title</title>
<topicref href="topic.dita" navtitle="Topic title">
<topicref href="nested.dita" navtitle="Nested title"/>
</topicref>
</map>
In MDITA, both ordered and unordered list items create <topicref>
elements.