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 parser for Markdown and HTML to allow using MDITA and HDITA as a source document format,
- and a transtype to generate Markdown from DITA source.
The Markdown DITA files need to use a subset of Markdown constructs for compatibility with DITA content models.
Markdown DITA or HTML DITA topics can only be used by linking to them in map files.
<map>
<topicref href="test.md" format="mdita"/>
<topicref href="test.html" format="hdita"/>
</map>
The format
attribute value must be set to mdita
or hdita
in order
to recognize files as Markdown DITA or HTML DITA, respectively; the file
extension is not used to recognize format.
See the syntax reference for XML and Markdown DITA correspondence.
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 themarkdown_gitbook
transtype.
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 |
-
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
.
To build the DITA-OT Markdown plug-in from source:
-
Run the Gradle distribution task to generate the plug-in distribution package:
./gradlew dist
The distribution ZIP file is generated under
build/distributions
.
To release and build distribution:
-
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.
Support this project and others by @jelovirt via GitHub Sponsors.
DITA-OT LwDITA is licensed for use under the Apache License 2.0.
Footnotes
-
Support MDITA map requires DITA-OT version 4.1. ↩