Markdown DITA syntax reference

Markdown DITA uses CommonMark as the underlying markup language.

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>

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 id="second_title">
    <title>Second title</title>

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:

  • concept
  • task
  • reference

They can be used to change the Markdown DITA topic type to one of the built-in structural specialization types.

# Task {.task}


1.  Command

<task id="task">
  <title>Task </title>


The following class values in header_attributes have a special meaning on header levels other than 1:

  • section
  • example

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>
      <title>Section title</title>
      <title>Example title</title>

Hard line breaks

A line break that is preceded by two or more spaces is parsed as a hard line break. Because DITA doesn't have a <br> element for line break, hard line breaks are converted into <?linebreak?> processing instructions.



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 ![Alt](test.jpg).


![Alt](test.jpg "Title")
<p>An inline <image href="test.jpg"><alt>Alt</alt></image>.</p>
<image href="test.jpg" placement="break">
  <image href="test.jpg">

Key references

Key reference can be used with shortcut reference links:

<xref keyref="key"/>
<image keyref="image-key"/>


The following inline elements are supported:

<ph status="deleted">strikethrough</ph>


Unordered can be marked up with either hyphen or asterisk:

*   one
*   two
    -   three
    -   four

Ordered can be marked up with either number or number sign, followed by a period:

1.  one
2.  two
    #.  three
    #.  four

Definition lists use the PHP Markdown Extra format:

:   Definition.

Each definition entry must have only one term and contain only inline content.


Tables use MultiMarkdown table extension format:

| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content      | *Long Cell*                 ||
| Content      | **Cell**      | Cell         |
  <tgroup cols="3">
    <colspec colname="col1"/>
    <colspec colname="col2" align="center"/>
    <colspec colname="col3" align="right"/>
        <entry>First Header </entry>
        <entry>Second Header </entry>
        <entry>Third Header </entry>
        <entry>Content </entry>
        <entry namest="col2" nameend="col3"><i>Long Cell</i></entry>
        <entry>Content </entry>
        <entry>Cell </entry>

Table cells may only contain inline content and column spans; block content and row spans are not supported by Markdown DITA.


YAML metadata block as defined in Pandoc pandoc_metadata_block can be used to specify different metadata elements. The supported elements are:

  • author
  • source
  • publisher
  • permissions
  • audience
  • category
  • keyword
  • resourceid

Unrecognized keys are output using data element.

  - Author One
  - Author Two
source: Source
publisher: Publisher
permissions: Permissions
audience: Audience
category: Category
  - Keyword1
  - Keyword2
  - Resourceid1
  - Resourceid2
workflow: review

# Sample with YAML header
<title>Sample with YAML header</title>
  <author>Author One</author>
  <author>Author Two</author>
  <permissions view="Permissions"/>
    <audience audience="Audience"/>
  <resourceid appid="Resourceid1"/>
  <resourceid appid="Resourceid2"/>
  <data name="workflow" value="review"/>