Topics

[ANN] MDITA_tools - scripts for bring Markdown documents into DITA #LwDITA #markdown

Larry Kollar
 

I cobbled up some Awk scripts to massage Markdown docs into MDITA topics, and thought they might be worth sharing.

mdsplit breaks up a Markdown document into individual topics, while building a DITA map or bookmap to preserve the hierarchy. If the document has a YAML header, the script uses that information to build a key file. One thing I'd like to do in the future is have the script look for places to use those keys, instead of having you walk through the document or doing a global search & replace.

infotype looks at MDITA topics and assigns a topic type (concept, task, or reference) based on what markup it finds in each topic. It's not a complex script, but in a small document (about 30 topics), it made reasonable choices for everything. Two of the topics tagged as concept should have been tasks with a single steps-unordered step, but that would take some pretty deep analysis for a non-human. :) If you tag any of the topics beforehand, the script respects your decision. If you have any familiarity with Awk, it's easy to add new rules (or modify existing ones).

You can also use these scripts to uplift pretty much anything that you can convert to Markdown into full-weight DITA, although you would probably want to go through the topics and fix a lot of inline elements afterward (is that italic text a citation or emphasized? is that bold text a UI element, window title, keystroke, or just strong?). While I wrote them for my own needs at home, I have also used them at work to quickly whack something together and clean it up before sending it to the CCMS.

Grab and enjoy: https://github.com/larrykollar/MDITA_tools