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>

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>

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.

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`
~~strikethrough~~
<b>bold</b>
<i>italic</i>
<codeph>code</codeph>
<ph status="deleted">strikethrough</ph>

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>