DITA and static site generators


despopoulos_chriss
 

The approach we took is to transform DITA to HTML in the browser.  This satisfies Docs as Code, in that a build simply takes our DITA source and places it on the server as is.  On the server side it's totally static.  But on the client side it's dynamic.  We use real-time filtering of the source to implement micro-content, for example.  Lots of metadata in a topic, and selective display at request time. 

I'll give a talk on how we do micro-content at the upcoming ConVex (replacement for DITA N. America and DITA Europe). 

We use a minimal subset of DITA -- Only use Topic, don't do specialization, and we don't support some of the more arcane features.  (We do support conrefs and keyrefs, though.)  We put this together about 8 years ago, when LwDITA was roughly a twinkle in Michael Priestly's eye, so we just did our own subset. 

The one thing we cannot do is directly port over to GitHub Pages.  GHP doesn't support AJAX, and we use AJAX to get the topic and the transform.  I finally need to figure out a workflow between GHP and our system, so we'll see how that goes.

FWIW...      cud


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.

http://docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.html

Regards,
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.


Michael McLoughlin
 

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.


Mark Giffin
 

Hi Michael,

What is missing for you to be able to use MDITA with Jekyll, Hugo, Docusaurus? Is it just the YAML header or other things?

I've converted between different flavors of markdown (there are lots of them), and often things like tables are also different.

Regards,
Mark Giffin
Mark Giffin Consulting, Inc.

On 3/19/2021 6:59 AM, Michael McLoughlin wrote:

That's really interesting, Wayne.

How are you handling things like keys and conrefs? 

What drew me to trying MDITA was that I could include keys, conrefs and filters directly into the Markdown (with a little HTML5). Admittedly, the tool support is not there yet for LwDITA and I'd really love someone to do a transform plugin that preserved the extended MDITA YAML header in the Markdown so they files could be plugged into Jekyll or Hugo or Docusaurus. Unfortunately I don't have the Java chops to write one myself.

I think being able to plugin DITA directly into static site generator would be a great advantage as an alternative to styling the HTML5 plugin or even the Oxygen Webhelp plugin.



Michael McLoughlin
 

On Fri, Mar 19, 2021 at 02:42 PM, Wayne Brissette wrote:
If we ever get back to doing DITA North America presentations, I might consider doing a session on what we did and how it's working out.

You should. I'd be up to see that. 

I think there are lot of us trying to find out a way with DITA on GitHub and getting it work in a docs-as-code workflow. I think your solution would certainly solicit interest.


Michael McLoughlin
 

On Fri, Mar 19, 2021 at 03:09 PM, Mica Semrick wrote:
You should have a look at the dita-ot.org website on github. Roger has done exactly this, he mixes dita output with markdown content and publishes using a static site generator.

Excellent idea. I'll see what I can steal. Isn't open source a wonderful thing!


Mica Semrick
 

You should have a look at the dita-ot.org website on github. Roger has done exactly this, he mixes dita output with markdown content and publishes using a static site generator.


On March 19, 2021 2:41:28 AM PDT, michael.mcloughlin@... wrote:

I was wondering if anyone is using DITA markdown output with a static site generator and what your experience is.

I've been playing with the MDITA flavor of LWDITA and outputting it to standard markdown. There exists markdown transforms to output to Gitbook/MdBook and even MKDocs. I've got content building nicely in Docsify too with the markdown_github output from the LwDITA plugin.

Is anyone automating DITA-OT builds to add markdown output to other static site generators like Jekyll, Hugo, Docusaurus, Gatsby etc.?


Wayne Brissette
 

Michael McLoughlin wrote on 2021-03-19 08:59:

That's really interesting, Wayne.

How are you handling things like keys and conrefs?
We don't they are writing in pure MD. We have constrained our DTDs and so we have content models they have to use. If their MD doesn't conform, it won't build and they get an error. Actually more times than not, my script fails telling them what it couldn't do or find. At that point it's up to engineering and the information developer to work out how to resolve it. Usually it's a formatting issue.

CommonMark/Markdown was always designed for lightweight authoring. I consider anything like keys and conrefs to be a bit heavier than we want to handle in MD, so if that's the requirement, I punt them to our DITA system. That said, I have built in a system whereby they can use custom variables and their is no limitation on that that looks like, so I've seen where product names, and indeed entire sentences are swapped out before the DITA is written.

I did the work in Python, although to be honest, I would have preferred to do this in Ruby because the Nokogiri XML library is better than LXML, but since I'm one of the few folks on my team that has any real experience with Ruby, we went with Python since that's the 'flavor of the day' and all of our new college grads we are bringing in understand it and can write it.

If we ever get back to doing DITA North America presentations, I might consider doing a session on what we did and how it's working out.

-Wayne


Michael McLoughlin
 

That's really interesting, Wayne.

How are you handling things like keys and conrefs? 

What drew me to trying MDITA was that I could include keys, conrefs and filters directly into the Markdown (with a little HTML5). Admittedly, the tool support is not there yet for LwDITA and I'd really love someone to do a transform plugin that preserved the extended MDITA YAML header in the Markdown so they files could be plugged into Jekyll or Hugo or Docusaurus. Unfortunately I don't have the Java chops to write one myself.

I think being able to plugin DITA directly into static site generator would be a great advantage as an alternative to styling the HTML5 plugin or even the Oxygen Webhelp plugin.


Wayne Brissette
 

michael.mcloughlin@puppet.com wrote on 2021-03-19 04:41:

Is anyone automating DITA-OT builds to add markdown output to other static site generators like Jekyll, Hugo, Docusaurus, Gatsby etc.?
We're going the other way... that is, we have built a pipeline that allows engineering to work more collaboratively with our information developers but using a combination of git, jenkins and markdown. We take the markdown, along with a YAML file with the metadata in it, and then using a custom script I wrote, generates fully fleshed out DITA. We automate the OT at this stage, but if for any reason we need to put this content into our CCMS, we have fully qualified DITA. We tried LWDITA, but we weren't happy with the results, so we built our own pipeline and processing. The nice thing is now our IDs are really collaborating for the first time with engineering at the design stage. We're still at the early stages of deployment, but for some teams this flow works. For others, the full DITA workflow still works better.

We have thought about generating CommonMark as one of outputs, but thus far, there hasn't been a pressing need. But for us I could see a need if one of our more traditional DITA teams needed to move content the other direction. However, I've not had the time to do much investigation into what this would really look like.

-Wayne


Michael McLoughlin
 

I was wondering if anyone is using DITA markdown output with a static site generator and what your experience is.

I've been playing with the MDITA flavor of LWDITA and outputting it to standard markdown. There exists markdown transforms to output to Gitbook/MdBook and even MKDocs. I've got content building nicely in Docsify too with the markdown_github output from the LwDITA plugin.

Is anyone automating DITA-OT builds to add markdown output to other static site generators like Jekyll, Hugo, Docusaurus, Gatsby etc.?
--
Michael McLoughlin
Senior Technical Writer
Puppet