How to Convert Markdown to AsciiDoc Using Pandoc

Markdown has a number of advantages, including:

• It’s a simple and uncomplicated file format.
• It can markup a range of common HTML elements, including headers, paragraphs, links, code, lists, and tables.
• It’s trivially easy to get started with; all you’d need are one of Markdown Guide, GitHub’s Markdown documentation, or Daring Fireball’s Markdown documentation and your favourite text editor. No fancy IDE required!
• It’s supported by a significant number of tools and services — one of the most notable being GitHub.

However, just because it’s ubiquitous and easy to get started with doesn’t mean it’s always the right choice, because it’s not without its shortcomings.

Here are a few key reasons why you shouldn’t use Markdown for technical documentation:

• There is no formalised standard (though this is changing)
• It only supports limited formatting functionality; admonitions, footnotes, advanced tables anyone?

Write the Docs founder Eric Holscher wrote an excellent article on why it’s not the right choice for technical documentation. I strongly recommend you read it!

If you and your team have already invested a lot of effort in creating Markdown-based documentation, it’s likely that you’ve already experienced more than a few of these limitations?

While it’s easy to get started with, and so many people know about it, the more you use it the more you’re going to hit these limitations and wish you had something better.

So, when this time comes, when you’re ready for a more feature-rich file format, such as AsciiDoc and reStructuredText, you’re going to need a tool to migrate your existing content. Gladly, there’s an open source tool that just about does all you need; it’s called Pandoc.

What is Pandoc?

Self-described as a “general markup converter”, Pandoc converts content from one markup format to another. It can read and write numerous formats, including:

• CommonMark, Daring Fireball Markdown, GitHub-Flavored Markdown, & Multi-Markdown
• DocBook
• EPUB
• HTML/HTML5
• LaTeX
• MediaWiki markup
• Microsoft Word docx
• ODT
• Subsets of Textile
• reStructuredText

As you can see from this list of file formats (and from its man page), Pandoc is an incredibly powerful tool. It formed the core of several migrations I undertook for ownCloud over the last few months, as their documentation was migrated from Sphinx-Doc to Antora.

During the course of those migrations, I learned so much about what it can do, and just how easy it makes converting file formats commonly used for technical documentation.

Install Pandoc

If you don’t have it installed already, it’s, generally, quite straightforward to do so. If you’re using a Linux distribution, then it should be available via your distribution’s package manager. Otherwise, use the instructions in the Pandoc documentation.

How To Convert Markdown to AsciiDoc

After you’ve installed Pandoc and have a sample Markdown file (or a host of files) ready to convert, use the following command example, changing the name of the input and output file as necessary. To summarise, this will convert the Markdown file file.md to AsciiDoc format, and name it file.adoc.

pandoc --atx-headers \
    --normalize \
    --verbose \
    --wrap=none \
    --toc \
    --reference-links \
    -s -S -o -t asciidoc path/to/your/asciidoc/file.adoc \
    path/to/your/markdown/file.md

The options passed to Pandoc will:

• Convert the headers to my preferred style, ATX style headers, instead of the default Setext style headers
• Add an automatic table of contents at the top of the file
• Not artificially wrap lines at an artificial line length. I prefer this as I’m a fan of one line per-sentence, one of the recommended AsciiDoc best practices.
• Use reference-style links, rather than inline links
• Produce output with an appropriate header and footer

Have a read of Pandoc’s man page and see if there are other options that would be helpful to use.

If you want to (recursively) convert an entire directory structure of Markdown files, here’s a Bash one-liner to help you do that:

find ./ -type f -name "*.md" \
    -exec pandoc \
    --atx-headers \
    --normalize \
    --verbose \
    --wrap=none \
    --toc \
    --reference-links \
    -s -S \
    -t asciidoc -o {}.adoc \;

This uses find to find all the Markdown files located under the current directory, and passes them to Pandoc to convert, just as in the earlier example.

The new files will be named the same as the Markdown file, but have an extra .adoc extension added to their name. For example, if the original file was myfile.md, then the new file will be named myfile.md.adoc. To get around that, here’s another Bash one-liner to remove all of the .md extensions from the AsciiDoc files:

find path/to/you/files/ -type f -name "*.adoc" -exec rename s/".md"/""/g {} \;

Want a More Natural Solution?

If you’re looking for a more natural solution for migrating from Markdown to AsciiDoc — one developed by the Asciidoctor team — then checkout my follow-up article on Kramdoc.

In Conclusion

And that’s the basics of how to migrate Markdown documents to AsciiDoc (or another format) using the power tool Pandoc.

As I alluded to, it’s not perfect, as there are things that it doesn’t quite get correct. For example, it doesn’t always convert code blocks from one format to another correctly. However, it does perform a majority of the migration legwork for you.

Imagine trying to do it on your own, or to create a custom migration script. If you did, or felt that you had to, you’d spend more time writing and maintaining the script than maintaining your content - which isn’t what you’re there to do. So I strongly recommend that you give it a go, and see how you go.

If you’ve been using it for some time, I’d love to hear your experiences with it.

CC Image Courtesy of Special Collections at Wofford College on Flickr.