XMLmind logo

XMLmind DITA Converter Manual

  

3. MDITA support Previous topic Parent topic Child topic Next topic

XMLmind DITA Converter (ditac) fully supports MDITA Opens in new window, which specifies how to write DITA topics and maps in Markdown logo Markdown Opens in new window. However for this to work, the file extension of the topic or map written in Markdown must be md, markdown, mdown, mkdn, mdwn, mkd or rmd.

Template of an MDITA topic lwdita_templates/mdita_topic.md Opens in new window:
---
id: ???
---

# Topic title here

Short description here.

Topic body starts here.
Template of an MDITA map lwdita_templates/mdita_map.md Opens in new window:
# Map title here {.map}
   
- [???](???)
  - [???](???)
  - [???](???)
- [???](???)
Notice the {.map} class attribute added to the title of the map. Without it, the above template would be translated to a DITA topic.

§ Implementation specificities

  • The encoding of an MDITA file is, by default, the system encoding (e.g. window-1252 on a Western PC).
    If you want to explicitly specify the encoding of an MDITA file, please save your file with a UTF-8 or UTF-16 BOM (Byte Order Mark) or add an encoding directive inside a comment anywhere at the beginning of your file. Example:
    <!-- -*- coding: iso-8859-1 -*- -->

Heading
=======

## Sub-heading

Paragraphs are separated
by a blank line.
    The above example should work fine because ditac understands the GNU Emacs file variable Opens in new window called coding.
  • When the ID of the MDITA topic is not explicitly specified (or specified as "???" like in the above template), the topic is automatically given an ID based on the basename(1) of the file containing it. Examples id="intro" if the MDITA topic is found in file "intro.md", id="Basic_Concepts" if found in "Basic Concepts.md".
  • Adding a {.concept} class attribute to the title of an MDITA topic may be used to generate a DITA concept rather than a DITA topic.
  • An internal link may be specified as [text](#TARGET_ID) or [text](#./TARGET_ID) or [text](#TOPIC_ID/TARGET_ID).
  • Out of the box, ditac Markdown parser is configured to support the commonmark 0.28 “Markdown dialect” plus all the following extensions:
    However, thanks to the flexmark-java Opens in new window software component used by ditac to implement Markdown support, all this can be configured by the means of -p load.mdita.XXX parameters. These load.mdita.XXX parameters are documented below.

§ Limitations

  • Without a {.map} class attribute added to the title of an MDITA map, this map is confused with a topic.
  • A link to another MDITA topic which is part of the same DITA document must be specified as [text](TOPIC_PATH#TOPIC_ID/TARGET_ID). Something like [text](TOPIC_PATH#TARGET_ID) or [text](TOPIC_PATH#./TARGET_ID) won’t work.

§ load.mdita.XXX parameters

The following load.mdita.XXX parameters are implicitely passed to ditac.
-p load.mdita.abbreviation true
-p load.mdita.admonition true
-p load.mdita.attributes true
-p load.mdita.definition true
-p load.mdita.footnotes true
-p load.mdita.gfm-strikethrough true
-p load.mdita.ins true
-p load.mdita.superscript true
-p load.mdita.tables true
-p load.mdita.typographic true
-p load.mdita.yaml-front-matter true
where abbreviation, admonition, attributes, etc, are all Markdown extensions, documented in Markdown extensions. This more or less corresponds to MDITA extended profile Opens in new window.
If, for example, you use the Github-flavored Markdown Opens in new window dialect, don’t need all the above Markdown extensions but need the autolink Markdown extension(2) and also the task lists Opens in new window syntax extension. then pass:
  • -p load.mdita.profile GITHUB
  • -p load.mdita.extensions min
  • -p load.mdita.autolink true
  • -p load.mdita.gfm-tasklist true
Supported “Markdown dialects” are COMMONMARK, COMMONMARK_0_26, COMMONMARK_0_27, COMMONMARK_0_28, FIXED_INDENT, KRAMDOWN, MARKDOWN, GITHUB_DOC, GITHUB, MULTI_MARKDOWN, PEGDOWN, PEGDOWN_STRICT. See Markdown Processor Emulation Opens in new window.
Parameter load.mdita.extensions may be given the following values:
none
No extensions.
min
Instructs ebookc to reset its extensions to the following minimal set of extensions:
The above minimal set of extensions corresponds to what’s described in the Markdown Cheatsheet Opens in new window.
This also more or less corresponds to MDITA core profile Opens in new window.
most
Default value. See default extensions.
 (1) The file extension is removed and non-NCName characters are replaced by '_'.
 (2) Turns plain text URLs and email addresses into <xref href="..."> elements.