db4rr / dita-ot-markdown

Markdown parser and output for DITA-OT

Markdown DITA for DITA-OT

DITA-OT Markdown plug-in contains

• a custom parser for Markdown to allow using Markdown DITA 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.

Requirements

DITA-OT 2.1 is required. Earlier versions of DITA-OT do not have the required extension points.

Build

1. To build the DITA-OT Markdown plug-in for local testing, first install the DITA-OT distribution JAR file dependencies by running gradle install from your clone of the DITA-OT repository. The required dependencies are installed to a local Maven repository in your home directory under .m2/repository/org/dita-ot/dost/.

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

   ./gradlew dist
   

   The distribution ZIP file is generated under build/distributions.

Install

1. Run the plug-in installation command:

   dita -install https://github.com/jelovirt/dita-ot-markdown/releases/download/1.1.0/com.elovirta.dita.markdown_1.1.0.zip
   

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

Usage

Using Markdown files as input

Markdown DITA topics can only be used by linking to them in map files.

<map>
  <topicref href="test.md" format="markdown"/>
</map>

The format attribute value must be set to markdown in order to recognize files as Markdown DITA; the file extension is not used to recognize format.

See Syntax reference for XML and Markdown DITA correspondence.

Generating Markdown output

The DITA-OT Markdown 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.

Donating

Support this project and others by @jelovirt via Paypal.

License

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