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>
  <topicref href="test1.md" format="markdown"></topicref>
  <!-- MDITA -->
  <topicref href="test2.md" format="mdita"></topicref>
  <!-- HDITA -->
  <topicref href="test3.html" format="hdita"></topicref>
</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

[^1]: Support MDITA map requires DITA-OT version 4.1.

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.