Re: DITA and static site generators

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.


Join to automatically receive all group messages.