Migrating from Markdown to structured authoring

Published on 24 January 2023 by Andrew Owen (3 minutes)

I’m a huge fan of Markdown. It’s great for wikis and writing content for static sites (most of the content on this site is written using it). But there comes a point in software documentation when the size of the project or the number of contributors has grown to the point that you need to impose some kind of structure on it. And that’s what structured docs are for. One of the main reasons you’d want to do that is to separate the content from the presentation. And that in turn enables you to present the content in different ways on various targets, such as print and online. But you’ve got all this content in Markdown already. So what are your options? You could recreate everything from scratch (don’t do that). Or you could migrate from Markdown to a structured authoring system.

I’ve written extensively about my enthusiasm for DocBook. In my view, it’s the best way to do structured authoring. But maybe you’re at the stage where most of your docs are written by developers, and you don’t have a technical writer on the team. As an aside, why are docs always the lowest priority in software development when they can be the deciding factor for a customer considering buying your software? There is a happy medium between Markdown and DocBook and it’s called AsciiDoc. You still write in plain text and the markup format is close enough to Markdown that developers can soon become familiar with it. But under the hood, the structure is the same as DocBook and you can export in that format.

The standard way to convert documentation from one format to another is Pandoc. However, when it comes to Markdown, there is a better way, as described by Matthew Setter in his blog. Created by Asciidoctor’s Dan Allen, Kramdoc is a Markdown to Asciidoc extension for kramdown (a Markdown conversion tool created by Thomas Leitner). The main requirement is Ruby, which is typically already installed on Linux and recent macOS releases. There are various ways to install Ruby on Windows, but generally I recommend using the Scoop package manager. When you have Ruby installed:

gem install kramdown-asciidoc

You’ll also need Asciidoctor itself. On Linux, you should be able to use your preferred package manager. On macOS, I recommend using Homebrew (brew install asciidoctor). On Windows, you can use gem install asciidoctor. Then, to convert an individual Markdown file to Asciidoc, enter: kramdoc -o=output.adoc input.md. See Mattew Setter’s previously mentioned article for one approach to doing batch conversion. When you’ve got all your content in Asciidoc format, you’ll need to build the document structure. This is effectively a table of contents. You can then publish to HTML. But there’s also a plug-in if you want to publish to PDF.

One difference between Asciidoc and standard Markdown is that it supports structured authoring. With unstructured authoring:

• The entire publication is often contained in a single file. After you go beyond a few chapters, it can soon become hard to manage.
• You can place content wherever you like. That makes it hard to produce consistent documentation.

But with structured authoring:

• A topic could contain a whole short chapter, or a only a section of a larger chapter.
• There are rules about where content can be used. For example, you can’t place an image above a topic title.

And if over time you find that even Asciidoc isn’t advanced enough for you, then you can go to full DocBook (asciidoctor -b docbook contents.adoc).

Notes

This week’s article is slightly truncated because I managed to accidentally click the back-button on my mouse without saving the original draft. I’ve requested a “leave this page?” browser warning from the TinaCMS team.