# Markdown DITA syntax

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.

To add a Markdown topic to a DITA publication, create a topic reference in your map and set the `@format` attribute to `markdown`. This allows the toolkit to recognize the source file as Markdown and convert it to DITA:

    <map>
      <topicref href="markdown-dita-topic.md" format="markdown"/>
    </map>

In this case, the first paragraph in the topic is treated as a body paragraph, and each heading level generates a nested topic.

The Markdown DITA format uses CommonMark as the underlying markup language, with several extensions as noted below. Markdown DITA files must be UTF-8 encoded.

The following Markdown constructs are parsed differently when the `@format` attribute is set to `markdown`.

## Titles and document structure

Each heading level generates 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 or PHP Markdown Extra special attributes can be used to define `id` or `outputclass` attributes:

    # Topic title {#carrot .juice audience=novice}

    <topic id="carrot" outputclass="juice" audience="novice">
      <title>Topic title</title>

If topic ID is not defined using header attributes, the ID is generated from title contents.

If the Markdown document doesn’t contain a level 1 heading, one is generated based on YAML metadata or from the document file name.

## Topic content

In Markdown DITA documents, all paragraphs appear inside the `body` element.

    # Topic title

    First paragraph.

    Second paragraph.

    <topic id="topic_title">
      <title>Topic title</title>
      <body>
        <p>First paragraph.</p>
        <p>Second paragraph.</p>
      </body>
    </topic>

## Specialization types

The following class values in header attributes have a special meaning on level 1 headings:

- `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}

    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>

The other way to use specialization types is by defining a schema for the document.

## Sections

The following class values in header attributes have a special meaning on heading 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>
      <body>
        <section>
          <title>Section title</title>
        </section>
        <example>
          <title>Example title</title>
        </example>
      </body>
    </topic>

## Tables

Tables use the MultiMarkdown table extension format:

    | First Header | Second Header | Third Header |
    | ------------ | :-----------: | -----------: |
    | Content      |          _Long Cell_        ||
    | Content      |   **Cell**    |         Cell |

Tables in Markdown DITA files are converted to the OASIS exchange table model:

    <table>
      <tgroup cols="3">
        <colspec colname="col1" colnum="1"/>
        <colspec colname="col2" colnum="2"/>
        <colspec colname="col3" colnum="3"/>
        <thead>
          <row>
            <entry colname="col1">First Header</entry>
            <entry align="center" colname="col2">Second Header</entry>
            <entry align="right" colname="col3">Third Header</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry colname="col1">Content</entry>
            <entry align="center" namest="col2" nameend="col3" colname="col2"><i>Long Cell</i></entry>
          </row>
          <row>
            <entry colname="col1">Content</entry>
            <entry align="center" colname="col2"><b>Cell</b></entry>
            <entry align="right" colname="col3">Cell</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

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

## Notes

Notes can be written using the syntax defined in the Material for MkDocs admonition extension.

> Note: Requires DITA-OT 4.1 or newer.

    !!! note

        Note content.

    <note>
      <p>Note Content.</p>
    </note>

Different note types can be defined by changing the type qualifier keyword.

    !!! info

        Info content.

    <note type="info">
      <p>Info Content.</p>
    </note>

## Markdown DITA map syntax

DITA maps can be written in Markdown using standard Markdown syntax for links and lists.

> Note: Requires DITA-OT 4.1 or newer.

In Markdown DITA, maps use the schema key in the YAML front matter block to define the file as a map:

    ---
    $schema: urn:oasis:names:tc:dita:xsd:map.xsd
    ---

    # 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>

Unordered list items create `<topicref>` elements, and ordered list items create `<topicref>` elements with `collection-type="sequence"`.

## Key definitions

Keys can be defined using standard Markdown syntax for link reference definitions.

    ---
    $schema: urn:oasis:names:tc:dita:xsd:map.xsd
    ---

    [key-name]: topic.md

    <map>
      <keydef href="topic.dita" navtitle="Topic title"/>
    </map>

Note that unlike in XML DITA, Markdown doesn't support defining keys in topic references.

## Relationship tables

Relationship tables are tables with links inside cells.

    ---
    $schema: urn:oasis:names:tc:dita:xsd:map.xsd
    ---

    | [Help](topic.md)  |                           |
    | ----------------- | ------------------------- |
    | [Topic](topic.md) | [Reference](reference.md) |

    <map>
      <reltable>
        <relheader>
          <relcolspec>
            <topicref href="help.dita"/>
          </relcolspec>
          <relcolspec/>
        </relheader>
        <relrow>
          <relcell>
            <topicref href="topic.dita"/>
          </relcell>
          <relcell>
            <topicref href="reference.dita"/>
          </relcell>
        </relrow>
      </reltable>
    </map>

## HTML

Raw HTML blocks are supported with some limitations.

    <figure>
      <img src="image1.png">
      <img src="image2.png">
    </figure>

    <fig>
      <image href="image1.png"/>
      <image href="image2.png"/>
    </fig>

HTML elements are converted to the equivalent DITA elements.

The current implementation has several limitations:

1. All open tags must be closed in the same block.

   If the tags are not opened in the same block, the output will not be as expected. (Close any open block tags before adding empty lines.)

       <figure>
         <img src="image1.png">

       Interlaced Markdown.

         <img src="image2.png">
       </figure>

       <fig>
         <image href="image1.png"/>
       </fig>
       <p>Interlaced Markdown.</p>
       <image href="image2.png"/>

## DITA

Raw DITA blocks are supported with some limitations.

    <sl>
      <sli>
        Simple list item
      </sli>
    </sl>

    <sl>
      <sli>
        Simple list item
      </sli>
    </sl>

The current implementation has several limitations:

1. All open tags must be closed in the same DITA block.

   If the tags are not opened in the same block, the output will not be as expected. (Close any open block tags before adding empty lines.)

       <sl>
         <sli>

       Simple list item

         </sli>
       </sl>

       <sl>
         <sli></sli>
       </sl>
       <p>Simple list item</p>

2. DITA tables are not supported because of the tag name conflict with HTML.

   (Use the MultiMarkdown table extension format, or HTML tables instead.)

## Common syntax

The following common Markdown constructs are processed in the same way for both `mdita` and `markdown` topics.

### 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.

    foo··
    baz

    <p>foo<?linebreak?>baz</p>

The LwDITA plug-in contains extensions for HTML5 and PDF outputs to generate line breaks.

### Links

The format of local link targets is detected based on file name extension. The following extensions are treated as DITA files:

extension | format
--- | ---
`.dita` | `dita`
`.xml` | `dita`
`.md` | `markdown`
`.markdown` | `markdown`

All other link targets detect the `format` from the file name extension and are treated as non-DITA files. Absolute link 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>

Links to DITA or Markdown files use the URI-based addressing as defined in the DITA specification, not HTML5 linking. This means that links to non-topic elements follow the DITA fragment identifier syntax:

    [Section](filename.md#topicID/sectionID)

    <xref href="filename.md#topicID/sectionID">Section</xref>

### Images

Images used in inline content are processed with inline placement. If a block-level image contains a title, it is treated as an image wrapped in a figure element:

    An inline ![Alt](test.jpg).

    ![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">
      <alt>Alt</alt>
    </image>
    <fig>
      <title>Title</title>
      <image href="test.jpg">
        <alt>Alt</alt>
      </image>
    </fig>

### Key references

Keys can be referenced using standard Markdown syntax for shortcut reference links:

    [key]
    [link text][key]
    ![image-key]

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

### Inline

The following inline elements are supported:

    **bold**
    _italic_
    `code`

    <b>bold</b>
    <i>italic</i>
    <codeph>code</codeph>

### Lists

Standard Markdown syntax is used for both ordered (numbered) and unordered (bulleted) lists.

Unordered list items can be marked up using either asterisks “`*`” or hyphens “`-`” as list markers:

    * one
    * two
      - three
      - four

    <ul>
      <li>one</li>
      <li>two
        <ul>
          <li>three</li>
          <li>four</li>
        </ul>
      </li>
    </ul>

Ordered lists use either numbers or number signs “`#`”, followed by a period:

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

    <ol>
      <li>one</li>
      <li>two
        <ol>
          <li>three</li>
          <li>four</li>
        </ol>
      </li>
    </ol>

> Note: Markdown DITA supports both loose and tight list spacing (with no blank lines between list items). MDITA treats all lists as loose, and wraps each list item in a paragraph (`<li><p>item</p></li>`).

Definition lists use the PHP Markdown Extra format with a single-line term followed by a colon and the definition:

    Term
    : Definition.

    <dl>
      <dlentry>
        <dt>Term</dt>
        <dd>Definition.</dd>
      </dlentry>
    </dl>

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

### Metadata

A YAML metadata block as defined in the pandoc_metadata_block extension can be used to specify metadata elements for the DITA prolog.

The supported elements are:

- `author`
- `source`
- `publisher`
- `permissions`
- `audience`
- `category`
- `keyword`
- `resourceid`

Any unrecognized keys are output using the `<data>` element.

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

    # Sample with YAML header

    <title>Sample with YAML header</title>
    <prolog>
      <author>Author One</author>
      <author>Author Two</author>
      <source>Source</source>
      <publisher>Publisher</publisher>
      <permissions view="Permissions"/>
      <metadata>
        <audience audience="Audience"/>
        <category>Category</category>
        <keywords>
          <keyword>Keyword1</keyword>
          <keyword>Keyword2</keyword>
        </keywords>
      </metadata>
      <resourceid appid="Resourceid1"/>
      <resourceid appid="Resourceid2"/>
      <data name="workflow" value="review"/>
    </prolog>