I recently started using AsciiDoc to write a new book. A great thing about it is that unlike Markdown, you can use AsciiDoc to write a book and get all of the features you want in a book, including linking between anything, captions for tables and figures, indexes, etc. Because this got me started using AsciiDoc I thought, “Wouldn’t it be nice if I could also use AsciiDoc to write blog posts like this one?”
Sadly, I quickly ran into a problem: I couldn’t find a good way to convert AsciiDoc into HTML, or even Markdown. There are tools to convert AsciiDoc to HTML, but for some reason they take the approach of including a ton of markup in the HTML (divs, spans, and attributes), and as far as I can tell there’s no way to turn off that markup.
It turns out that converting AsciiDoc to HTML without including a bunch of undesired CSS is a problem, and converting AsciiDoc to Markdown is also a problem. The page I linked to shows the best way I’ve found to convert AsciiDoc to Markdown, which can then be converted to CSS-free HTML. In case that page ever disappears, the basic commands are:
Install pandoc and asciidoc:
sudo apt install pandoc asciidoc
Convert asciidoc to docbook:
asciidoc -b docbook foo.adoc
Convert docbook to markdown:
If you ever need to convert Docbook to AsciiDoc, this Pandoc command seems to work well:
pandoc --wrap=none -f docbook -t asciidoc \ DocbookFile.xml > AsciiDocFile.adoc
pandoc --wrap=none -f html -t asciidoc myfile.html > myfile.adoc
The wrapping part of that command isn’t 100% necessary, but if you don’t use it, Pandoc will wrap the plain paragraph text, which I don’t like because I’ll be editing the resulting AsciiDoc text.
Here’s some of the AsciiDoc text that this command generated:
As a brief note to self, if you need to convert an Asciidoc file named test1.adoc to HTML format, this command works:
asciidoc -o test1.html test1.adoc
Of course a key here is that you need the
asciidoc command installed. I installed it on my Mac with Homebrew, something like
brew install asciidoc. I don’t like the HTML that this approach generates, so I’ll keep looking for something better.