Converting Maven APT docs to Markdown

In a project I worked on many moons ago we were writing documentation in the APT format, and publishing to HTML and PDF using a Maven-based toolchain.

APT served us well, but it hasn’t been supported or improved by the community in a long time. When the time came to update the documentation for a major release, we decided to switch to using Markdown, which was a format everyone was already familiar with, and allowed the team to take advantage of all the tools, such as Sublime plugins, that support Markdown.

Converting APT documents to Markdown is a two step process of APT -> XHTML -> Markdown using the Doxia converter which can be downloaded here and the excellent swiss-army document format conversion tool Pandoc:

# Converting over the existing APT docs to XHTML via Doxia converter
> java -jar ~/Downloads/doxia-converter-1.2-jar-with-dependencies.jar -in your_doc.apt \
  -from apt -out ./ -to xhtml

# Convert resulting XHTML to Markdown
> pandoc -o your_doc.md your_doc.apt.xhtml

The end result will require a bit of manual fixing up, but in my experience it was pretty minimal and beats doing it manually or writing your own converter.

This entry was posted in General, Software Development, Tools and tagged , , . Bookmark the permalink.

One Response to Converting Maven APT docs to Markdown

  1. Alix says:

    Many thanks for this post !

    As complement:
    – pandoc “–wrap=none” option is useful when your apt have some text syntax (bold, italic, …)
    – After conversion of Maven websites, some patterns deletion should be done :

    sed -i ‘/::: {.section}/d’ “markdown/myFile.md”
    sed -i ‘/:::/d’ “markdown/myFile.md”
    sed -i ‘/{.externalLink}/d’ “markdown/myFile.md”

Leave a Reply

Your email address will not be published. Required fields are marked *