Goodbye LwDITA
I’ve switched back to Markdown, but Lightweight DITA was useful and has its place in documentation.
Oasis released the LwDITA standard in 2018. It has reduced features compared to standard DITA, but can accept source files in Markdown, DITA, and HTML. It became possible to write in Markdown and build content using DITA-aware tools and a ditamap.
Uses of Lightweight DITA
The intention was to accommodate teams where engineers wanted to write certain documentation in Markdown, and technical authors wanted to have the benefits of DITA for most everything else.
I used it to build the previous version of this site, with an eye on learning the capabilities of LwDITA, as compared to the full version of DITA I was using in the office. It became useful as the company grew. .
As my employer acquired startups, we migrated the documentation to DITA, which we’d chosen as our common platform for documentation. A couple of projects employed some version of Markdown for documentation. Lightweight DITA gave us a path to building that content with DITA tool, quickly and cleanly, and we didn’t have to do a huge amount of work to convert it.
Eventually, authors tended to migrate all their documentation to full DITA as soon as they could, and just because they wanted to. LwDITA might have worked for a long time.
Here are some of the things I learned while working with Lightweight DITA.
HTML tables beat Markdown
Markdown tables have always been pretty limited, and they didn’t work any better in LwDITA. It seems that tables were always fixed at 100 percent of page width and columns were proportionally sized.
I also wanted to use more complex tables, containing paragraphs and other elements, which is impossible in Markdown tables. I resolved this by using HTML tables. HTML tables have way more capability than plain Markdown tables: a cell can span multiple rows or columns, can contain a paragraph or a large image, and can contain random spaces without creating build issues. Most importantly, you can set the column widths with a colgroup element, as you would with any HTML or DITA table.
I could have used DITA tables throughout the site, but I thought using HTML would make my content portable. HTML tables are more ready to be published by any platform that accepts Markdown, and I wanted to keep my options open.
AI can now make HTML tables
When I included HTML tables, I did it the old fashioned way: I used the DITA conref feature to include a document containing only the HTML table, which I edited separately. Since Markdown allows you to place HTML directly in a document, just embed the HTML tables in your Markdown. When you want to change an HTML table, use AI to draft the HTML markup. For example, start with a csv file or some descriptive text; then paste it in the chat with your favorite LLM and prompt it to create the HTML table that you need.
You can still use straight DITA tables in LwDITA
For a document with a series of complicated tables, I decided to use a standard DITA topic. I did that as long as I was using LwDITA, and it solved the problem with proportional-width tables. I like that DITA tables can be updated in in a WYSIWYG interface like Oxygen XML Editor, which is the way most people want to update tables–Not as a blob of Markdown or DITA.
Now that this site is using Jekyll, the DITA tables have been converted to HTML as well. The DITA tables didn’t require a lot of updating, after all, so I expect them to be easy to maintain, even in HTML.
A standard DITA topic is still the easiest option for managing tables in LwDITA, if you’re a DITA author and you have a DITA-aware editor.
Forget about H3 headings
MDITA does not support level three headings in the same way that Markdown does. Your output might have H3s, but you can’t arbitrarily create one, and DITA-OT will ignore them. Any time you use <H3> or ### the text might disappear from your document.
This makes authors deal with one of the less popular features of DITA. You can have an three or more heading levels, as long as they are created by including a topic into another topic. But in any given topic, you can only have two levels of headings.
Sometimes you just want an H3 and it doesn’t make sense to break the topic up in preparation for “reuse” that will never happen. This article, for example, has five H3 headings.
Some features not included
There are also some differences in functionality where Lightweight DITA lacks the functionality of standard DITA. If you’re not a heavy DITA user, and your content is in Markdown, chances are you don’t need these features.
- No reltables. In standard DITA, you can create a reltable map and use it to manage which topics link to which other topics. It’s a handy way to control all the links in one place.
- No ditaval. Conditional formatting is a built-in feature of DITA. Standard DITA can build multiple versions of your document for different audiences. For example, you could turn out different version of the documentation for Mac, Windows, and Linux. The ditaval file controls which content is included or not included when you build a particular version of documentation, and can select content down to the element level. LwDITA ignores any ditaval files.
The common theme is that these tools involve using an attribute on a DITA element at some point. And since markdown doesn’t offer any place to store attributes, it was sensible to leave all this functionality out of lightweight DITA.
LwDITA handles HTML content differently
When you add HTML in the ditamap, its treated differently from Markdown or DITA. Your HTML pages won’t have the any of the headers, footers, or navigation that your other pages have if you’re building classic web help. This might come as a surprise. The inclusion of HTML content was done with marketing teams in mind, and the feature assumes that they’ll provide their own CSS.
Just like the solution for tables, if you have HTML and you were counting on the static site generator to provide the styling a page template – paste that HTML into a Markdown file.
For more about LwDITA
Find out more about Lightweight DITA from Oasis.
Or Read Carlos Evia’s book, “Creating intelligent content with Lightweight DITA”.