3.1. Markdown extensions

Abbreviations

Converts plain text abbreviations (e.g. IBM) to <abbr> elements.
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.abbreviation false to ditac.
Example:
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
is converted to:
<p>The <keyword>HTML</keyword> specification is maintained 
by  the <keyword>W3C</keyword>.</p>
which is rendered as:
The HTML specification is maintained by the W3C.

Admonitions

Syntax for creating admonitions such as notes, tips, warnings, etc.
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.admonition false to ditac.
After the "!!!" tag, the admonition type must be one of "note", "attention","caution", "danger", "fastpath", "important", "notice", "remember", "restriction", "tip","trouble", "warning".
A note example not having a title:
!!! note ""
    Support is limited to bug reports.
is converted to:
<note>
  <p>Support is limited to bug reports.</p>
</note>
which is rendered as:
Note
Note
Support is limited to bug reports.
A tip example having a title:
!!! tip "How do you do a hard reboot on an iPad?"
    Press and hold both the **Home** and **Power** buttons 
    until your iPad&reg; reboots.

    You can release both buttons when you see Apple&reg; logo.
is converted to:
<note type="tip">
  <div outputclass="note-title role-h4">How do you
  do a hard reboot on an iPad?</div>

  <p>Press and hold both the <b>Home</b> and <b>Power</b> 
  buttons until your iPad® reboots.</p>

  <p>You can release both buttons when you see 
  Apple® logo.</p>
</note>
which is rendered as:
Tip
Tip
How do you do a hard reboot on an iPad?
Press and hold both the Home and Power buttons until your iPad® reboots.
You can release both buttons when you see Apple® logo.

Attributes

Syntax for adding attributes to the generated HTML elements:
attributes -> '{' attribute_spec ( S attribute_spec)* '}'

attribute_spec ->   name=value
                  | name='value'
                  | name="value"
                  | #id
                  |.class

Remember
Remember
An easy rule to remember
If an {...} specification is separated by space characters from some plain text (e.g. some plain text {...}) then the attributes are added to the parent element of the text.
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.attributes false to ditac.
Example:
The *circumference { .first-term }* is the length of one circuit along the
circle, or the distance around the circle. {#circumference}
is converted to:
<p id="circumference">The <i outputclass="first-term">circumference</i> 
is the length of one circuit along the circle, or the distance around 
the circle.</p>
which is rendered as:
The circumference is the length of one circuit along the circle, or the distance around the circle.
Attention
Attention
Pitfall
By default, heading IDs are not “rendered” in HTML (which is somewhat counterintuitive). You must pass -p load.mdita.renderer.RENDER_HEADER_ID true to ditac get them “rendered”.

Automatic links

This Markdown syntax extension is disabled by default. In order to enable it, pass parameter -p load.mdita.autolink true to ditac.
Example:
Please send your bug reports to support@xmlmind.com, a public,
moderated, mailing list. More information in https://xmlmind.com/.
is converted to:
<p>Please send your bug reports to <xref 
href="mailto:support@xmlmind.com">support@xmlmind.com</xref>,
a public, moderated, mailing list. More information in <xref
href="https://xmlmind.com/">https://xmlmind.com/</xref>.</p>
which is rendered as:
Please send your bug reports to support@xmlmind.com, a public, moderated, mailing list. More information in https://www.xmlmind.com/.

Definition lists

Syntax for creating definition lists, that is <dl>, <dt> and <dd> elements.
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.definition false to ditac.
Example:
Glossary:

LED
: Light emitting diode.

ABS
: Antilock braking system.

ESC
ESP
: Electronic stability control, also known as Electronic Stability Program.

: On motorcycles, ESC/ESP is called *Traction Control*.

  > Ducati was one of the first to introduce a true competition-level 
  > traction control system (**DTC**) on a production motorcycle.

EBA
: Emergency brake assist.
is converted to:
<p>Glossary:</p>
<dl>
   <dlentry>
     <dt>LED</dt>
     <dd>
       <p>Light emitting diode.</p>
     </dd>
   </dlentry>
   <dlentry>
     <dt>ABS</dt>
     <dd>
       <p>Antilock braking system.</p>
     </dd>
   </dlentry>
   <dlentry>
     <dt>ESC</dt>
     <dt>ESP</dt>
     <dd>
       <p>Electronic stability control, also known as
       Electronic Stability Program.</p>
     </dd>
     <dd>
       <p>On motorcycles, ESC/ESP is called <i>Traction Control</i>.</p>
       <lq>
         <p>Ducati was one of the first to introduce a
         true competition-level traction control system 
         (<b>DTC</b>) on a production motorcycle.</p>
       </lq>
     </dd>
   </dlentry>
   <dlentry>
     <dt>EBA</dt>
     <dd>
       <p>Emergency brake assist.</p>
     </dd>
   </dlentry>
 </dl>
which is rendered as:
Glossary:
LED
Light emitting diode.
ABS
Antilock braking system.
ESC
ESP
Electronic stability control, also known as Electronic Stability Program.
On motorcycles, ESC/ESP is called Traction Control.
Ducati was one of the first to introduce a true competition-level traction control system (DTC) on a production motorcycle.
EBA
Emergency brake assist.
Remember
Remember
Remember that:
  • The leading ":" character of a definition must be followed by one or more space characters.
  • Terms must be separated from the previous definition by a blank line.
  • A blank line is not allowed between two consecutive terms.
  • A blank line is allowed before a definition.

Footnotes

Syntax for creating footnotes and footnote references.
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.footnotes false to ditac.
Example:
The differences between the programming languages C++[^1] and Java can be
traced to their heritage.

[^1]: The C++ Programming Language by Bjarne Stroustrup.

C++[^1] was designed for systems and applications programming, extending the
procedural programming language C[^2].

[^2]: The C Programming Language by Brian Kernighan and Dennis Ritchie.

      Originally published in 1978.
is converted to:
<p>The differences between the programming languages
C++<xref href="#./__FN1" type="fn"/> and Java can
be traced to their heritage.</p>

<div>
  <fn id="__FN1">The C++ Programming Language by
  Bjarne Stroustrup.</fn>
</div>

<p>C++<xref href="#./__FN1" type="fn"/> was designed 
for systems and applications programming, extending 
the procedural programming 
language C<xref href="#./__FN2" type="fn"/>.</p>

<div>
  <fn id="__FN2">The C Programming Language by 
  Brian Kernighan and Dennis Ritchie. 
  <p>Originally published in 1978.</p> </fn>
</div>
which is rendered as:
The differences between the programming languages C++(1) and Java can be traced to their heritage.
C++(1) was designed for systems and applications programming, extending the procedural programming language C(2).

Strikethrough and subscript

Converts
  • tagged text "~~something deleted~~" to <del>something deleted</del>, which is rendered as: something deleted
  • tagged text "~a subscript~" to <sub>a subscript<sub/>, which is rendered as: a subscript
This Markdown syntax extension, which is part of the MDITA Core Profile and the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.gfm-strikethrough false to ditac.

Ins

Converts tagged text "++something new++" to <ins>something new</ins>, which is rendered as: something new
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.ins false to ditac.

Superscript

Converts tagged text "^a superscript^" to <sup>a superscript</sup>, which is rendered as: a superscript
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.superscript false to ditac.

Tables

Converts pipe "|" delimited text to <table> elements.
This Markdown syntax extension, which is part of the MDITA Core Profile and the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.tables false to ditac.
Simple table example:
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 | Cell 1,2 | Cell 1,3 |
| Cell 2,1 | Cell 2,2 | Cell 2,3 |
is converted to:
<table >
  <tgroup cols="3">
    <thead>
      <row valign="middle">
        <entry align="center">Header 1</entry>
        <entry align="center">Header 2</entry>
        <entry align="center">Header 3</entry>
      </row>
    </thead>
    <tbody>
      <row valign="middle">
        <entry>Cell 1,1</entry>
        <entry>Cell 1,2</entry>
        <entry>Cell 1,3</entry>
      </row>
      <row valign="middle">
        <entry>Cell 2,1</entry>
        <entry>Cell 2,2</entry>
        <entry>Cell 2,3</entry>
      </row>
    </tbody>
  </tgroup>
</table>
which is rendered as:
Header 1 Header 2 Header 3
Cell 1,1 Cell 1,2 Cell 1,3
Cell 2,1 Cell 2,2 Cell 2,3
Table example having centered and right-aligned columns:
| Header 1 | Header 2        | Table Header 3 |
| -------- | :-------------: | -------------: |
| Cell 1,1 | Table cell 1,2  | Cell 1,3       |
| Cell 2,1 | Cell 2,2        | Cell 2,3       |
is converted to:
<table>
  <tgroup cols="3">
    <thead>
      <row valign="middle">
        <entry align="center">Header 1</entry>
        <entry align="center">Header 2</entry>
        <entry align="right">Table Header
        3</entry>
      </row>
    </thead>
    <tbody>
      <row valign="middle">
        <entry>Cell 1,1</entry>
        <entry align="center">Table cell
        1,2</entry>
        <entry align="right">Cell 1,3</entry>
      </row>
      <row valign="middle">
        <entry>Cell 2,1</entry>
        <entry align="center">Cell 2,2</entry>
        <entry align="right">Cell 2,3</entry>
      </row>
    </tbody>
  </tgroup>
</table>
which is rendered as:
Header 1 Header 2 Table Header 3
Cell 1,1 Table cell 1,2 Cell 1,3
Cell 2,1 Cell 2,2 Cell 2,3
Table example having cells spanning several columns and a caption:
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 + 1,2     || Cell 1,3 |
| Cell 2,1 + 2,2 + 2,3         |||
| Cell 3,1 | Cell 3,2 | Cell 3,3 |
[Table caption here]
is converted to:
<table>
  <title>Table caption here</title>
  <tgroup cols="3">
    <colspec colname="c1" rowheader="headers"/>
    <colspec colname="c2" rowheader="headers"/>
    <colspec colname="c3" rowheader="headers"/>
    <thead>
      <row valign="middle">
        <entry align="center">Header 1</entry>
        <entry align="center">Header 2</entry>
        <entry align="center">Header 3</entry>
      </row>
    </thead>
    <tbody>
      <row valign="middle">
        <entry nameend="c2" namest="c1">Cell 1,1
        + 1,2</entry>
        <entry>Cell 1,3</entry>
      </row>
      <row valign="middle">
        <entry nameend="c3" namest="c1">Cell 2,1
        + 2,2 + 2,3</entry>
      </row>
      <row valign="middle">
        <entry>Cell 3,1</entry>
        <entry>Cell 3,2</entry>
        <entry>Cell 3,3</entry>
      </row>
    </tbody>
  </tgroup>
</table>
which is rendered as:

Table B-1. Table caption here

Header 1 Header 2 Header 3
Cell 1,1 + 1,2 Cell 1,3
Cell 2,1 + 2,2 + 2,3
Cell 3,1 Cell 3,2 Cell 3,3

Typographic characters

Converts
  • "'" to apostrophe &rsquo;, which is rendered as in word: "don’t"
  • "..." and ". . ." to ellipsis &hellip;, which are both rendered as: …
  • "--" to en dash &ndash;, which is rendered as: –
  • "---" to em dash &mdash;, which is rendered as: —
  • single quoted 'some text' to &lsquo;some text&rsquo;, which is rendered as: ‘some text’
  • double quoted "some text" to &ldquo;some text&rdquo;, which is rendered as: “some text”
  • double angle quoted <<some text>> to &laquo;some text&raquo;, which is rendered as: «some text»
This Markdown syntax extension, which is part of the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.typographic false to ditac.
If you don’t want some of the above plain text sequences to be processed, specify:
-p load.mdita.typographic.ENABLE_QUOTES false
Do not process single quotes, double quotes, double angle quotes.
-p load.mdita.typographic.ENABLE_SMARTS false
Do not process "'", "...", ". . .", "--", "---".

YAML front matter

Syntax for adding metadata to the generated DITA topic or map, that is, for populating the <prolog> element of a DITA topic and the <topicmeta> element of a DITA map.
These metadata are specified by key/value pairs written using a subset of the YAML Opens in new window (see also http://yaml.org/) syntax.
Supported metadata are:
  • audience
  • author
  • category
  • created (maps to <critdates>/<created>)
  • keyword (maps to <keywords>/<keyword>)
  • permissions
  • publisher
  • resourceid
  • revised (maps to <critdates>/<revised>)
  • source
Any other metadata is translated to DITA element <data>.
This Markdown syntax extension, which is part of the MDITA Core Profile and the MDITA Extended Profile, is enabled by default. In order to disable it, pass parameter -p load.mdita.yaml-front-matter false to ditac.
Example:
---
author:
  - Brian W. Kernighan
  - Dennis Ritchie
publisher: Prentice Hall
created: 1978/01/01
revised: 1988/01/01
---
is converted to:
<prolog>
  <author>Brian W. Kernighan</author>
  <author>Dennis Ritchie</author>
  <publisher>Prentice Hall</publisher>
  <critdates>
    <created date="1978/01/01"/>
    <revised modified="1988/01/01"/>
  </critdates>
</prolog>

Other extensions

The following Markdown syntax extensions are also supported:
  • anchorlink
  • aside
  • emoji
  • enumerated-reference
  • gfm-issues
  • gfm-tasklist
  • gfm-users
  • toc
  • wikilink
  • youtube-embedded
All the above extensions are disabled by default. In order to enable an extension, pass parameter -p load.mdita.EXTENSION_NAME true to ditac. For example: -p load.mdita.emoji true
Any extension listed in this section may be parameterized by passing parameter -p load.mdita.EXTENSION_NAME.PARAMETER_NAME PARAMETER_VALUE(3) to ditac. Examples:
  • -p load.mdita.emoji.ATTR_IMAGE_SIZE 16
  • -p load.mdita.emoji.ATTR_ALIGN ""
  • -p load.mdita.emoji.USE_IMAGE_TYPE IMAGE_ONLY
  • -p load.mdita.emoji.ROOT_IMAGE_PATH https://www.webpagefx.com/tools/emoji-cheat-sheet/graphics/emojis/
More generally, the Markdown parser (pseudo EXTENSION_NAME is "parser") and the HTML renderer (pseudo EXTENSION_NAME is "renderer") may also be parameterized this way. For example, automatically generate an ID for all headings not already having an ID and “render” all heading IDs in HTML(4):
-p load.mdita.renderer.GENERATE_HEADER_ID true
-p load.mdita.renderer.RENDER_HEADER_ID true
More information about extensions and their parameters in Extensions Opens in new window (flexmark-java Opens in new window is the software component used by ditac to parse Markdown and convert it to HTML).

 (1) The C++ Programming Language by Bjarne Stroustrup.
 (2) The C Programming Language by Brian Kernighan and Dennis Ritchie.
Originally published in 1978.
 (3) The only types supported for PARAMETER_VALUE are: string, boolean (true or false), integer and any enumerated type.
 (4) By default, heading IDs are not “rendered” in HTML, which is somewhat counterintuitive.