Re: DITA and static site generators

Mark Giffin

Michael, thanks for the info on trying to use MDITA with various static site generators. I'm on the Lightweight DITA subcommittee and it's good to hear how people are trying to use it.

I haven't used the markdown_github DITA OT transtype much. The docs for it say it converts DITA files to GitHub-Flavored Markdown, which does not have YAML headers. This is equivalent to "core profile" MDITA. Probably the markdown_github plugin could be modified to output something like "extended profile" MDITA, which does allow YAML headers.

I can also imagine a fairly simple DITA OT plugin that would convert MDITA markdown into a markdown flavor that is compatible with a given static site generator. So if you want it to just pass through HTML tables embedded in the markdown, you could do it.

There is no markdown flavor that will work with all or even most static site generators, that I know of. Since there is no real standard for markdown, your static site generator (if you use one) tends to be the validator for your flavor's syntax. Unless you have an editor that will do it. Oxygen has something like this for MDITA.

I've used the Lightweight DITA markdown flavor (MDITA) for a couple clients over the last couple of years and it has worked pretty well for them as it is right now. They are mainly using it as an easier authoring format. It fits in well with an existing DITA setup where some people are using full XML DITA and others want something simple. You can put XML and mdita topic files in the same map. It's easy to publish the markdown/mdita and have it fit in with the existing DITA publishing. I have found that late-model versions of the DITA Open Toolkit handle it pretty well for my purposes.

I hear that Adobe has been using MDITA internally in some places for a while. There are others also. This is using the current Lightweight DITA Committee Note, which is not the finished specification.

Mark Giffin
Mark Giffin Consulting, Inc.

On 3/20/2021 4:46 AM, Michael McLoughlin wrote:
Hi Mark,
             Principally the lack of YAML headers. I have noticed too that the markdown_github transform changes HTML tables into PHP Extra format tables - and not very well. Not sure why they cannot just be left in HTML.
I think LwDITA has a ways to go before it is enterprise ready. Not sure how much it will change now before its release. I had an exchange recently with  Michael Priestley on LinkedIn and he reckons it'll be early 2022 before it comes out.

I think the improvements it needs will only really come about once it is let loose in the real world and people start developing more plugins and the tools folks like Oxygen and Adobe start really getting involved.

Join to automatically receive all group messages.