Skip to content

Latest commit

 

History

History
141 lines (106 loc) · 3.59 KB

MDITA-syntax.md

File metadata and controls

141 lines (106 loc) · 3.59 KB
Raw

In 2017, the Markdown plug-in was superseded by the LwDITA plug-in, which was bundled with DITA-OT 3.0, and added new formats for Lightweight DITA. The mdita format implements the subset of Markdown features proposed in the latest specification drafts, but differs in some ways from the original Markdown DITA format.

To apply the stricter LwDITA-specific processing to a Markdown topic, create a topic reference in your map and set the @format attribute to mdita:

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

In this case, the first paragraph in the topic is treated as a short description, and tables are converted to DITA <simpletable> elements.

The MDITA format uses CommonMark as the underlying markup language. MDITA files must be UTF-8 encoded.

The MDITA parser processes topics according to the MDITA “Extended profile” proposed for LwDITA. The "Core profile" can be enabled for custom parser configurations.

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

Titles and document structure

The first heading level generates a topic and the second heading level a section:

# Topic title

## Section title
<topic id="topic_title">
  <title>Topic title</title>
  <body>
    <section>
      <title>Section title</title>
    </section>
  </body>
</topic>

The ID is generated automatically from the title content.

Topic content

The first paragraph is treated as a <shortdesc> element.

# Topic title

First paragraph.

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

Tables

Tables use the MultiMarkdown table extension format:

| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content      |    _Cell_     |         Cell |
| Content      |   **Cell**    |         Cell |

Tables in MDITA files are converted to DITA <simpletable> elements:

<simpletable>
  <sthead>
    <stentry>
      <p>First Header</p></stentry>
    <stentry>
      <p>Second Header</p></stentry>
    <stentry>
      <p>Third Header</p></stentry>
  </sthead>
  <strow>
    <stentry>
      <p>Content</p></stentry>
    <stentry>
      <p><i>Cell</i></p></stentry>
    <stentry>
      <p>Cell</p></stentry>
  </strow>
  <strow>
    <stentry>
      <p>Content</p></stentry>
    <stentry>
      <p><b>Cell</b></p></stentry>
    <stentry>
      <p>Cell</p></stentry>
  </strow>
</simpletable>

Note Cell alignment information is not preserved, as the @align attribute is are not available for <simpletable> elements.

Table cells may only contain inline content.

MDITA map syntax

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

Note: Requires DITA-OT 4.1 or newer.

In MDITA, maps use the file name extension mditamap to define the file as a map:

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

In MDITA, both ordered and unordered list items create <topicref> elements.