DITA-OT³ Markdown Support

One of the most popular posts on this site is Marking Down DITA, my 2015 article on the rise of Markdown as an alternative input method for DITA projects. The sustained interest is at least partly due to its citation in the first Lightweight DITA committee note on the upcoming standard.

That post provided background information for people who are new to the concept of lightweight markup languages and how they relate to more structured authoring formats like DITA.

— But that was years ago, and a lot has happened since then…

At this year’s DITA Europe conference in Berlin, I gave a follow-up talk that explained how DITA Open Toolkit 3.0 supports Markdown right out of the box along with the alternative authoring formats proposed for Lightweight DITA.

This article provides a summary of that presentation and highlights recent changes in the toolkit’s Markdown support.

Using Markdown with DITA-OT

The level of Markdown support that DITA Open Toolkit provides depends on the version of the toolkit that you are using.

Since I wrote Marking Down DITA, several versions of the DITA-OT Markdown plug-in were released to improve Markdown parsing, resolve issues and support additional features, including:

• A new markdown_github transtype generates GitHub-flavored Markdown (GFM), which can be used to publish DITA content to GitHub wikis, or other publishing environments that support GFM.
• Markdown input with multiple first-level headings will now be wrapped in a <dita> composite topic.
• E-mail autolinks in Markdown input are now generated with the mailto: URI scheme.
• Strike-through markup in Markdown input is now handled correctly.
• The md extension can now be used in @format attribute values to trigger Markdown processing.
• YAML headers are now supported to include metadata in input and output.

Installing with DITA-OT 2

If you’re still running DITA-OT 2.2 – 2.5, you can install the plug-in as described in my earlier post:

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

Built into DITA-OT 3

The Markdown support that was previously provided by the external dita-ot-markdown plug-in has been extended and bundled with the default toolkit installation for DITA-OT 3.0.

This means you can now use Markdown topics in DITA publications (or convert DITA source files to Markdown) right out of the box without having to install any additional plug-ins first.

What about Lightweight DITA?

The new Lightweight DITA plug-in replaces the earlier Markdown plug-in and builds on its capabilities to provide additional support for Lightweight DITA (LwDITA).

New Authoring Formats

DITA Open Toolkit 3.0 provides preview support for the MDITA and HDITA authoring formats planned for LwDITA.

These new formats have been proposed¹ as alternative representations of DITA content in Markdown or HTML.

MDITA

MDITA is the LwDITA authoring format based on Markdown. It is designed for users who want to write structured content with the minimum of overhead, but who also want to take advantage of the reuse mechanisms associated with the DITA standard and the multi-channel publishing afforded by standard DITA tooling.

Recent proposals include two profiles for MDITA:

• “Core profile” — based on GitHub Flavored Markdown and includes elements that are common to other Markdown implementations.
• “Extended profile” — borrows features from other Markdown flavors to represent a broader range of DITA content with existing plain-text syntax conventions.

So what’s the difference?

The Markdown DITA parser included in the org.lwdita plug-in provides preliminary support for LwDITA profiles — and additional Markdown constructs.

To apply LwDITA-specific processing to Markdown topics, set the @format attribute on a topic reference to mdita:

<map>
  <topicref href="mdita-topic.md" format="mdita"/>
</map>

In this case, the first paragraph in the topic will be treated as a short description, for example, and additional metadata can be specified for the topic via a YAML front matter block.

Note: MDITA parsing is stricter than the more lenient document parsing approach that is applied to Markdown documents when the @format attribute is set to markdown.

HDITA

HDITA is the LwDITA authoring format based on HTML5 to support structured content authoring with tools designed for HTML authoring.

The HDITA parser included in the org.lwdita plug-in provides preliminary support for these constructs.

To apply LwDITA-specific processing to HTML topics, set the @format attribute to hdita:

<map>
  <topicref href="hdita-topic.html" format="hdita"/>
</map>

Using Lightweight DITA now

So while the Lightweight DITA standard is still evolving, the basic principles are already clear — and DITA-OT³ now offers the processing tools you need to use Markdown in your DITA publishing workflows.

The toolkit’s support for Lightweight DITA will mature further as the emerging standard solidifies, but there’s no need to purchase proprietary software to make it easier for authors to contribute to DITA publications, facilitate review processes with less technical audiences, or feed DITA content into Markdown-based publishing systems.

DITA-OT³ enables a broad range of new use cases, and we can look forward to hearing more about what people are doing with these new capabilities in upcoming conference presentations and future articles — here and elsewhere.

Stay tuned…

Resources

• daringfireball.net/projects/markdown
• infotexture.net/2015/04/dita-ot-markdown-plugin
• github.com/jelovirt/org.lwdita (new in DITA-OT 3.0)
• github.com/jelovirt/dita-ot-markdown (deprecated)