Skip to content

Markdown DITA syntax

Jump to bottom
Jarno Elovirta edited this page Jul 13, 2024 · 23 revisions

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

Clone this wiki locally