Lightweight DITA for DITA-OT

The DITA-OT LwDITA plug-in supersedes the previously released Markdown plug-in for DITA-OT and adds additional features to support Lightweight DITA.

Note The LwDITA plug-in is included in DITA Open Toolkit 3.0 and newer.

It contains:

• a custom SAX parser for Markdown and HTML to allow using Markdown and HDITA as source document formats,
• and a transtype to generate Markdown from DITA source.

Markdown source document formats

Markdown-based source files must use a subset of Markdown constructs for compatibility with DITA content models.

Two different Markdown source formats are supported:

• Markdown DITA
• MDITA (LwDITA)

For a comparison of these two formats, see Format comparison in the LwDITA Wiki.

Usage

Using Markdown-based and HDITA files as input

Markdown-based or HTML DITA topics can only be used by linking to them in map files.

<map>
  <!-- Markdown DITA -->
  <topicref href="test1.md" format="md"/>
  <topicref href="test1.md" format="markdown"/>

  <!-- MDITA -->
  <topicref href="test2.md" format="mdita"/>

  <!-- HDITA -->
  <topicref href="test3.html" format="hdita"/>
</map>

The format attribute value must be set to the values shown above in order to recognize files as Markdown DITA, MDITA, or HDITA, respectively; the file extension is not used to recognize format.

Generating Markdown output

The DITA-OT LwDITA plug-in extends the DITA Open Toolkit with additional output formats (transformation types) that can be used to publish DITA content as Markdown.

• To publish Markdown DITA files, use the markdown transtype.

• To generate GitHub Flavored Markdown files, use the markdown_github transtype.

• To publish GitHub Flavored Markdown and generate a SUMMARY.md table of contents file for publication via GitBook, use the markdown_gitbook transtype.

Requirements

LwDITA plug-in	DITA-OT	Java
≤ 2.5	2.4	1.8
≥ 3.0	3.4	1.8
≥ 4.0	3.4	11
≥ 5.2	3.4 1	11

Install

1. Run the plug-in installation command:

   On DITA-OT version 3.5 and newer:

   $ dita install org.lwdita

   On DITA-OT version 3.2–3.4:

   $ dita --install org.lwdita

   On DITA-OT version 3.1 and older:

   $ dita --install https://github.com/jelovirt/org.lwdita/releases/download/2.3.2/org.lwdita-2.3.2.zip

The dita command line tool requires no additional configuration; running DITA-OT using Ant requires adding plug-in contributed JAR files to the CLASSPATH with e.g. -lib plugins/org.lwdita.

Build

To build the DITA-OT Markdown plug-in from source:

1. Run the Gradle distribution task to generate the plug-in distribution package:

   ./gradlew dist

   The distribution ZIP file is generated under build/distributions.

Release

To release and build distribution:

1. Tag release in master branch using semantic version as tag name, e.g. 1.2.3.

   GitHub Actions will create

   • a distribution ZIP and upload it to GitHub Release for the tag,
   • a JAR release that is published to github.com/jelovirt/org.lwdita/packages,
   • a pull request to github.com/dita-ot/registry to update the release to DITA-OT plug-in registry.

Donating

Support this project and others by @jelovirt via GitHub Sponsors.

License

DITA-OT LwDITA is licensed for use under the Apache License 2.0.

Footnotes

1. Support MDITA map requires DITA-OT version 4.1. ↩