Markdown DITA syntax reference
Markdown DITA syntax
Markdown DITA uses
as the underlying markup language.
Pandoc
UTF
DITAspecializations
Markdown
CommonMark
Markdown DITA files must be UTF-8 encoded.
Titles and document structure
Each header level will generate a topic and associated title:
# Topic title
## Nested topic title<topic id="topic_title">
<title>Topic title</title>
<topic id="nested_topic_title">
<title>Nested topic title</title>
</topic>
</topic>
Pandoc
header_attributes can be used to define id or
outputclass attributes:
# Topic title {#carrot .juice}<topic id="carrot" outputclass="juice">
<title>Topic title</title>
If topic ID is not defined using header_attributes, the ID is generated from title contents.
Pandoc
pandoc_title_block
extension can be used to group multiple level 1 headers under a common
title:
% Common title
# Topic title
# Second title<topic id="common_title">
<title>Common title</title>
<topic id="topic_title">
<title>Topic title</title>
</topic>
<topic id="second_title">
<title>Second title</title>
</topic>
</topic>
Topic content
In LwDITA compatible documents (MDITA) the first paragraph is treated as a shortdesc element.
In generic Markdown documents all paragraphs appear inside the body element.
Specialization types
The following class values in
header_attributes have a special meaning on level 1 headers:
They can be used to change the Markdown DITA topic type to one of the built-in structural specialization
types.
# Task {.task}
Context
1. Command
Info.<task id="task">
<title>Task </title>
<taskbody>
<context>
<p>Context</p>
</context>
<steps>
<step>
<cmd>Command</cmd>
<info>
<p>Info.</p>
</info>
</step>
</steps>
</taskbody>
</task>
Sections
The following class values in
header_attributes have a special meaning on header levels other than 1:
They are used to generate
section and
example
elements:
# Topic title
## Section title {.section}
## Example title {.example}<topic id="topic_title">
<title>Topic title</title>
<body>
<section>
<title>Section title</title>
</section>
<example>
<title>Example title</title>
</example>
</body>
</topic>
Links
The format of local link targets is detected based on file extension. The following extensions are treated as
DITA files:
extension
format
.dita
dita
.xml
dita
.md
markdown
.markdown
markdown
All other link targets use format from file extension and are treated as non-DITA files.
Absolute links targets are treated as external scope
links:
[Markdown](test.md)
[DITA](test.dita)
[HTML](test.html)
[External](http://www.example.com/test.html)<xref href="test.md">Markdown</xref>
<xref href="test.dita">DITA</xref>
<xref href="test.html" format="html">HTML</xref>
<xref href="http://www.example.com/test.html" format="html" scope="external">External</xref>
Images
imagesMarkdown
Images used in inline content will result in inline placement. If a block level image contains a title, it will
be treated as an image wrapped in
figure:
An inline .
<p>An inline <image href="test.jpg"><alt>Alt</alt></image>.</p>
<image href="test.jpg" placement="break">
<alt>Alt</alt>
</image>
<fig>
<title>Title</title>
<image href="test.jpg">
<alt>Alt</alt>
</image>
</fig>
Key references
Key reference can be used with
shortcut
reference
links:
[key]
![image-key]<xref keyref="key"/>
<image keyref="image-key"/>
Inline
The following inline elements are
supported:
**bold**
*italic*
`code`
~~strikethrough~~<b>bold</b>
<i>italic</i>
<codeph>code</codeph>
<ph status="deleted">strikethrough</ph>
Lists
Unordered can be marked up with either hyphen or ampersand:
* one
* two
- three
- four<ul>
<li>one</li>
<li>two
<ul>
<li>three</li>
<li>four</li>
</ul>
</li>
</ul>
Ordered can be marked up with either number or number sign, followed by a period:
1. one
2. two
#. three
#. four<ol>
<li>one</li>
<li>two
<ol>
<li>three</li>
<li>four</li>
</ul>
</li>
</ul>
Definition lists use the
PHP
Markdown Extra format:
Term
: Definition.<dl>
<delentry>
<dt>Term</dt>
<dd>Defintion.</dd>
</delentry>
</dl>
Each definition entry must have only one term and contain only inline content.
Tables
tablesMarkdown
Tables use
MultiMarkdown table
extension format:
| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content | *Long Cell* ||
| Content | **Cell** | Cell |<table>
<tgroup cols="3">
<colspec colname="col1"/>
<colspec colname="col2" align="center"/>
<colspec colname="col3" align="right"/>
<thead>
<row>
<entry>First Header </entry>
<entry>Second Header </entry>
<entry>Third Header </entry>
</row>
</thead>
<tbody>
<row>
<entry>Content </entry>
<entry namest="col2" nameend="col3"><i>Long Cell</i></entry>
</row>
<row>
<entry>Content </entry>
<entry><b>Cell</b></entry>
<entry>Cell </entry>
</row>
</tbody>
</tgroup>
</table>
Table cells may only contain inline content and column spans; block content and row spans are not supported by
Markdown DITA.